curly-templates 0.1.1 → 0.2.0

data/Gemfile

@@ -1,2 +1,10 @@
 source :rubygems
+
 gemspec
+
+platform :ruby do
+  gem 'yard'
+  gem 'yard-tomdoc'
+  gem 'redcarpet'
+  gem 'github-markup'
+end

data/README.md

@@ -29,7 +29,61 @@ Installing Curly is as simple as running `gem install curly-templates`. If you'r
 using Bundler to manage your dependencies, add this to your Gemfile
 
 ```ruby
-gem 'curly-templates', '~> 0.1.0', require: 'curly'
+gem 'curly-templates', '~> 0.1.0'
+```
+
+
+How to use Curly
+----------------
+
+In order to use Curly for a view or partial, use the suffix `.curly` instead of
+`.erb`, e.g. `app/views/posts/_comment.html.curly`. Curly will look for a
+corresponding presenter class named `Posts::CommentPresenter`. By convention,
+these are placed in `app/presenters/`, so in this case the presenter would
+reside in `app/presenters/posts/comment_presenter.rb`. Note that presenters
+for partials are not prepended with an underscore.
+
+Add some HTML to the partial template along with some Curly variables:
+
+```html
+<!-- app/views/posts/_comment.html.curly -->
+<div class="comment">
+  <p>
+    {{author_link}} posted {{time_ago}} ago.
+  </p>
+
+  {{body}}
+</div>
+```
+
+The presenter will be responsible for filling in the variables. Add the necessary
+Ruby code to the presenter:
+
+```ruby
+# app/presenters/posts/comment_presenter.rb
+class Posts::CommentPresenter < Curly::Presenter
+  presents :comment
+
+  def body
+    BlueCloth.new(@comment.body).to_html
+  end
+
+  def author_link
+    link_to(@comment.author.name, @comment.author, rel: "author")
+  end
+
+  def time_ago
+    time_ago_in_words(@comment.created_at)
+  end
+end
+```
+
+The partial can now be rendered like any other, e.g. by calling
+
+```ruby
+render 'comment', comment: comment
+render comment
+render collection: post.comments
 ```
 
 

data/Rakefile

@@ -52,14 +52,6 @@ task :default => :spec
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "#{name} #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -rubygems -r ./lib/#{name}.rb"

data/curly-templates.gemspec

@@ -4,15 +4,15 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
 
   s.name              = 'curly-templates'
-  s.version           = '0.1.1'
-  s.date              = '2013-01-23'
+  s.version           = '0.2.0'
+  s.date              = '2013-02-07'
 
   s.summary     = "Free your views!"
   s.description = "A view layer for your Rails apps that separates structure and logic."
 
   s.authors  = ["Daniel Schierbeck"]
-  s.email    = 'dasch@zendesk.com'
-  s.homepage = 'http://github.com/zendesk/curly-templates'
+  s.email    = 'daniel.schierbeck@gmail.com.com'
+  s.homepage = 'https://github.com/dasch/curly'
 
   s.require_paths = %w[lib]
 
@@ -20,8 +20,10 @@ Gem::Specification.new do |s|
 
   s.add_dependency("actionpack", "~> 3.2.11")
 
+  s.add_development_dependency("railties", "~> 3.2.11")
   s.add_development_dependency("rake")
   s.add_development_dependency("rspec", "~> 2.12.0")
+  s.add_development_dependency("genspec")
 
   # = MANIFEST =
   s.files = %w[
@@ -34,7 +36,11 @@ Gem::Specification.new do |s|
     lib/curly/presenter.rb
     lib/curly/railtie.rb
     lib/curly/template_handler.rb
+    lib/generators/curly/controller/controller_generator.rb
+    lib/generators/curly/controller/templates/presenter.rb.erb
+    lib/generators/curly/controller/templates/view.html.curly.erb
     spec/curly_spec.rb
+    spec/generators/controller_generator_spec.rb
     spec/presenter_spec.rb
     spec/spec_helper.rb
     spec/template_handler_spec.rb

data/lib/curly.rb

@@ -26,7 +26,7 @@
 # See Curly::Presenter for more information on presenters.
 #
 module Curly
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 
   REFERENCE_REGEX = %r(\{\{(\w+)\}\})
 
@@ -35,6 +35,11 @@ module Curly
 
   class << self
 
+    # Compiles a Curly template to Ruby code.
+    #
+    # template - The template String that should be compiled.
+    #
+    # Returns a String containing the Ruby code.
     def compile(template)
       source = template.inspect
       source.gsub!(REFERENCE_REGEX) { compile_reference($1) }
@@ -42,6 +47,13 @@ module Curly
       source
     end
 
+    # Whether the Curly template is valid. This includes whether all
+    # references are available on the presenter class.
+    #
+    # template        - The template String that should be validated.
+    # presenter_class - The presenter Class.
+    #
+    # Returns true if the template is valid, false otherwise.
     def valid?(template, presenter_class)
       references = extract_references(template)
       methods = presenter_class.available_methods.map(&:to_s)
@@ -68,4 +80,6 @@ module Curly
   end
 end
 
+require 'curly/presenter'
+require 'curly/template_handler'
 require 'curly/railtie' if defined?(Rails)

data/lib/curly/presenter.rb

@@ -12,7 +12,7 @@ module Curly
   #
   # A presenter is always instantiated with a context to which it delegates
   # unknown messages, usually an instance of ActionView::Base provided by
-  # Rails. See Curly::Handler for a typical use.
+  # Rails. See Curly::TemplateHandler for a typical use.
   #
   # Examples
   #
@@ -36,6 +36,7 @@ module Curly
   #   presenter.author #=> "Jackie Chan"
   #
   class Presenter
+
     # Initializes the presenter with the given context and options.
     #
     # context - An ActionView::Base context.
@@ -48,18 +49,62 @@ module Curly
       end
     end
 
+    # The key that should be used to cache the view.
+    #
+    # Unless `#cache_key` returns nil, the result of rendering the template
+    # that the presenter supports will be cached. The return value will be
+    # part of the final cache key, along with a digest of the template itself.
+    #
+    # Any object can be used as a cache key, so long as it
+    #
+    # - is a String,
+    # - responds to #cache_key itself, or
+    # - is an Array of a Hash whose items themselves fit either of these
+    #   criteria.
+    #
+    # Returns the cache key Object or nil if no caching should be performed.
     def cache_key
       nil
     end
 
+    # The duration that the view should be cached for. Only relevant if
+    # `#cache_key` returns a non nil value.
+    #
+    # If nil, the view will not have an expiration time set.
+    #
+    # Examples
+    #
+    #   def cache_duration
+    #     10.minutes
+    #   end
+    #
+    # Returns the Fixnum duration of the cache item, in seconds, or nil if no
+    #   duration should be set.
     def cache_duration
       nil
     end
 
+    # Whether a method is available to templates rendered with the presenter.
+    #
+    # Templates can reference "variables", which are simply methods defined on
+    # the presenter. By default, only public instance methods can be
+    # referenced, and any method defined on Curly::Presenter itself cannot be
+    # referenced. This means that methods such as `#cache_key` and #inspect are
+    # not available. This is done for safety purposes.
+    #
+    # This policy can be changed by overriding this method in your presenters.
+    #
+    # method - The Symbol name of the method.
+    #
+    # Returns true if the method can be referenced by a template,
+    #   false otherwise.
     def method_available?(method)
       self.class.available_methods.include?(method)
     end
 
+    # A list of methods available to templates rendered with the presenter.
+    #
+    # Returns an Array of Symbol method names.
     def self.available_methods
       public_instance_methods - Curly::Presenter.public_instance_methods
     end
@@ -73,6 +118,9 @@ module Curly
       self.presented_names += args
     end
 
+    # Delegates private method calls to the current view context.
+    #
+    # The view context, an instance of ActionView::Base, is set by Rails.
     def method_missing(method, *args, &block)
       @_context.public_send(method, *args, &block)
     end

data/lib/curly/railtie.rb

@@ -1,7 +1,8 @@
 module Curly
   class Railtie < Rails::Railtie
+    config.app_generators.template_engine :curly
+
     initializer 'curly.initialize_template_handler' do
-      require 'curly/template_handler'
       ActionView::Template.register_template_handler :curly, Curly::TemplateHandler
     end
   end

data/lib/curly/template_handler.rb

@@ -3,10 +3,28 @@ require 'action_view'
 require 'curly'
 
 class Curly::TemplateHandler
+
+  # The name of the presenter class for a given view path.
+  #
+  # path - The String path of a view.
+  #
+  # Examples
+  #
+  #   Curly::TemplateHandler.presenter_name_for_path("foo/bar")
+  #   #=> "Foo::BarPresenter"
+  #
+  # Returns the String name of the matching presenter class.
   def self.presenter_name_for_path(path)
     "#{path}_presenter".camelize
   end
 
+  # Handles a Curly template, compiling it to Ruby code. The code will be
+  # evaluated in the context of an ActionView::Base instance, having access
+  # to a number of variables.
+  #
+  # template - The ActionView::Template template that should be compiled.
+  #
+  # Returns a String containing the Ruby code representing the template.
   def self.call(template)
     presenter_class = presenter_name_for_path(template.virtual_path)
 

data/lib/generators/curly/controller/controller_generator.rb

@@ -0,0 +1,30 @@
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+module Curly
+  module Generators
+    class ControllerGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("../templates", __FILE__)
+
+      argument :actions, type: :array, default: [], banner: "action action"
+
+      def create_view_files
+        base_views_path = File.join("app/views", class_path, file_name)
+        base_presenters_path = File.join("app/presenters", class_path, file_name)
+
+        empty_directory base_views_path
+        empty_directory base_presenters_path
+
+        actions.each do |action|
+          @view_path = File.join(base_views_path, "#{action}.html.curly")
+          @presenter_path = File.join(base_presenters_path, "#{action}_presenter.rb")
+          @action = action
+          @presenter_name = "#{class_name}::#{action.capitalize}Presenter"
+
+          template "view.html.curly.erb", @view_path
+          template "presenter.rb.erb", @presenter_path
+        end
+      end
+    end
+  end
+end

data/lib/generators/curly/controller/templates/presenter.rb.erb

@@ -0,0 +1,10 @@
+class <%= @presenter_name %> < Curly::Presenter
+  # If you need to assign variables to the presenter, you can use the
+  # `presents` method.
+  #
+  #   presents :foo, :bar
+  #
+  # Any public method defined in a presenter class will be available
+  # to the Curly template as a variable. Consider making these methods
+  # idempotent.
+end

data/lib/generators/curly/controller/templates/view.html.curly.erb

@@ -0,0 +1,2 @@
+<h1><%= class_name %>#<%= @action %></h1>
+<p>Find me in <%= @view_path %></p>

data/spec/curly_spec.rb

@@ -1,5 +1,4 @@
 require 'spec_helper'
-require 'active_support/core_ext/string/output_safety'
 require 'curly'
 
 describe Curly do
@@ -38,7 +37,6 @@ describe Curly do
   end
 
   let(:presenter) { presenter_class.new }
-  let(:context) { double("context", presenter: presenter) }
 
   it "compiles Curly templates to Ruby code" do
     evaluate("{{foo}}").should == "FOO"
@@ -85,8 +83,16 @@ describe Curly do
     end
   end
 
-  def evaluate(template)
+  def evaluate(template, &block)
     code = Curly.compile(template)
-    context.instance_eval(code)
+    context = double("context", presenter: presenter)
+
+    context.instance_eval(<<-RUBY)
+      def self.render
+        #{code}
+      end
+    RUBY
+
+    context.render(&block)
   end
 end

data/spec/generators/controller_generator_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'genspec'
+require 'generators/curly/controller/controller_generator'
+
+describe Curly::Generators::ControllerGenerator do
+  with_args "animals/cows", "foo"
+
+  it "generates a Curly template for each action" do
+    subject.should generate("app/views/animals/cows/foo.html.curly") {|content|
+      expected_content = "<h1>Animals::Cows#foo</h1>\n" +
+        "<p>Find me in app/views/animals/cows/foo.html.curly</p>\n"
+
+      content.should == expected_content
+    }
+  end
+
+  it "generates a Curly presenter for each action" do
+    subject.should generate("app/presenters/animals/cows/foo_presenter.rb") {|content|
+      expected_content = (<<-RUBY).gsub(/^\s{8}/, "")
+        class Animals::Cows::FooPresenter < Curly::Presenter
+          # If you need to assign variables to the presenter, you can use the
+          # `presents` method.
+          #
+          #   presents :foo, :bar
+          #
+          # Any public method defined in a presenter class will be available
+          # to the Curly template as a variable. Consider making these methods
+          # idempotent.
+        end
+      RUBY
+
+      content.should == expected_content
+    }
+  end
+end

data/spec/presenter_spec.rb

@@ -1,6 +1,4 @@
 require 'spec_helper'
-require 'active_support/all'
-require 'curly/presenter'
 
 describe Curly::Presenter do
   class CircusPresenter < Curly::Presenter

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'active_support/all'

data/spec/template_handler_spec.rb

@@ -1,7 +1,4 @@
 require 'spec_helper'
-require 'active_support/core_ext/string/output_safety'
-require 'active_support/core_ext/hash'
-require 'curly/template_handler'
 
 describe Curly::TemplateHandler do
   let :presenter_class do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: curly-templates
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-23 00:00:00.000000000 Z
+date: 2013-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -27,6 +27,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.11
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -59,8 +75,24 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.12.0
+- !ruby/object:Gem::Dependency
+  name: genspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A view layer for your Rails apps that separates structure and logic.
-email: dasch@zendesk.com
+email: daniel.schierbeck@gmail.com.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -74,11 +106,15 @@ files:
 - lib/curly/presenter.rb
 - lib/curly/railtie.rb
 - lib/curly/template_handler.rb
+- lib/generators/curly/controller/controller_generator.rb
+- lib/generators/curly/controller/templates/presenter.rb.erb
+- lib/generators/curly/controller/templates/view.html.curly.erb
 - spec/curly_spec.rb
+- spec/generators/controller_generator_spec.rb
 - spec/presenter_spec.rb
 - spec/spec_helper.rb
 - spec/template_handler_spec.rb
-homepage: http://github.com/zendesk/curly-templates
+homepage: https://github.com/dasch/curly
 licenses: []
 post_install_message: 
 rdoc_options:
@@ -93,7 +129,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3306742458990639659
+      hash: -1725225944803924182
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -108,5 +144,7 @@ specification_version: 2
 summary: Free your views!
 test_files:
 - spec/curly_spec.rb
+- spec/generators/controller_generator_spec.rb
 - spec/presenter_spec.rb
 - spec/template_handler_spec.rb
+has_rdoc: