RubyGems - curly-templates - Versions diffs - 0.8.0 → 0.9.0 - Mend

curly-templates 0.8.0 → 0.9.0

Files changed (9) hide show

data/CHANGELOG.md +9 -0
data/README.md +123 -8
data/curly-templates.gemspec +4 -2
data/lib/curly.rb +1 -1
data/lib/curly/presenter.rb +21 -0
data/lib/curly/template_handler.rb +2 -0
data/lib/rails/projections.json +16 -0
data/spec/template_handler_spec.rb +16 -0
metadata +5 -3

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,9 @@
+### Unreleased
+### Curly 0.9.0 (June 4, 2013)
+* Allow running setup code before rendering a Curly view. Simply add a `#setup!`
+  method to your presenter – it will be called by Curly just before the view is
+  rendered.
+  *Daniel Schierbeck*

data/README.md CHANGED Viewed

@@ -22,6 +22,24 @@ or [Handlebars](http://handlebarsjs.com/), Curly is different in some key ways:
   object methods that are in turn used by the template.
+### Is it ready to use in production?
+Yes! While still a young project, it's being used in a rather large Rails app
+at Zendesk, where it performs admirably.
+### Table of Contents
+1. [Installing](#installing)
+2. [How to use Curly](#how-to-use-curly)
+3. [Presenters](#presenters)
+    1. [Layouts and Content Blocks](#layouts-and-content-blocks)
+    1. [Examples](#examples)
+4. [Caching](#caching)
 Installing
 ----------
@@ -87,17 +105,114 @@ render collection: post.comments
 ```
-Is it ready to use in production?
----------------------------------
+Presenters
+----------
-Yes! While still a young project, it's being used in a rather large Rails app
-at Zendesk, where it performs admirably.
+Presenters are classes that inherit from `Curly::Presenter` – they're usually placed in
+`app/presenters/`, but you can put them anywhere you'd like. The name of the presenter
+classes match the virtual path of the view they're part of, so if your controller is
+rendering `posts/show`, the `Posts::ShowPresenter` class will be used. Note that Curly
+is only used to render a view if a template can be found – in this case, at
+`app/views/posts/show.html.curly`.
+Presenters can declare a list of accepted parameters using the `presents` method:
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+end
+```
+A parameter can have a default value:
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+  presents :comment, default: nil
+end
+```
+Any public method defined on the presenter is made available to the template:
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+  def title
+    @post.title
+  end
+  def author_link
+    # You can call any Rails helper from within a presenter instance:
+    link_to author.name, profile_path(author), rel: "author"
+  end
+  private
+  # Private methods are not available to the template, so they're safe to
+  # use.
+  def author
+    @post.author
+  end
+end
+```
+Presenter methods can even take an argument. Say your Curly template has the content
+`{{t.welcome_message}}`, where `welcome_message` is an I18n key. The following presenter
+method would make the lookup work:
+```ruby
+def t(key)
+  translate(key)
+end
+```
+That way, simple ``functions'' can be added to the Curly language. Make sure these do not
+have any side effects, though, as an important part of Curly is the idempotence of the
+templates.
+### Layouts and Content Blocks
+Both layouts and content blocks (see [`content_for`](http://api.rubyonrails.org/classes/ActionView/Helpers/CaptureHelper.html#method-i-content_for))
+use `yield` to signal that content can be inserted. Curly works just like ERB, so calling
+`yield` with no arguments will make the view usable as a layout, while passing a Symbol
+will make it try to read a content block with the given name:
+```ruby
+# Given you have the following Curly template in app/views/layouts/application.html.curly
+#
+#   <html>
+#     <head>
+#       <title>{{title}}</title>
+#     </head>
+#     <body>
+#       <div id="sidebar">{{sidebar}}</div>
+#       {{body}}
+#     </body>
+#   </html>
+#
+class ApplicationLayout < Curly::Presenter
+  def title
+    "You can use methods just like in any other presenter!"
+  end
+  def sidebar
+    # A view can call `content_for(:sidebar) { "some HTML here" }`
+    yield :sidebar
+  end
+  def body
+    # The view will be rendered and inserted here:
+    yield
+  end
+end
+```
-Examples
---------
+### Examples
-Here is a simple Curly template -- it will be looked up by Rails automatically.
+Here is a simple Curly template – it will be looked up by Rails automatically.
 ```html
 <!-- app/views/posts/show.html.curly -->
@@ -205,7 +320,7 @@ end
 ### Static Caching
 Static caching will only be enabled for presenters that define a non-nil `#cache_key`
-method (see "Dynamic Caching.")
+method (see [Dynamic Caching.](#dynamic-caching))
 In order to make a deploy expire the cache for a specific view, set the version of the
 view to something new, usually by incrementing by one:

data/curly-templates.gemspec CHANGED Viewed

@@ -4,8 +4,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
   s.name              = 'curly-templates'
-  s.version           = '0.8.0'
-  s.date              = '2013-05-22'
+  s.version           = '0.9.0'
+  s.date              = '2013-06-04'
   s.summary     = "Free your views!"
   s.description = "A view layer for your Rails apps that separates structure and logic."
@@ -28,6 +28,7 @@ Gem::Specification.new do |s|
   # = MANIFEST =
   s.files = %w[
+    CHANGELOG.md
     Gemfile
     README.md
     Rakefile
@@ -43,6 +44,7 @@ Gem::Specification.new do |s|
     lib/generators/curly/controller/controller_generator.rb
     lib/generators/curly/controller/templates/presenter.rb.erb
     lib/generators/curly/controller/templates/view.html.curly.erb
+    lib/rails/projections.json
     spec/compiler_spec.rb
     spec/generators/controller_generator_spec.rb
     spec/presenter_spec.rb

data/lib/curly.rb CHANGED Viewed

@@ -26,7 +26,7 @@
 # See Curly::Presenter for more information on presenters.
 #
 module Curly
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
   # Compiles a Curly template to Ruby code.
   #

data/lib/curly/presenter.rb CHANGED Viewed

@@ -55,6 +55,27 @@ module Curly
       end
     end
+    # Sets up the view.
+    #
+    # Override this method in your presenter in order to do setup before the
+    # template is rendered. One use case is to call `content_for` in order
+    # to inject content into other templates, e.g. a layout.
+    #
+    # Example
+    #
+    #   class Posts::ShowPresenter < Curly::Presenter
+    #     presents :post
+    #
+    #     def setup!
+    #       content_for :page_title, @post.title
+    #     end
+    #   end
+    #
+    # Returns nothing.
+    def setup!
+      # Does nothing.
+    end
     # The key that should be used to cache the view.
     #
     # Unless `#cache_key` returns nil, the result of rendering the template

data/lib/curly/template_handler.rb CHANGED Viewed

@@ -42,6 +42,8 @@ class Curly::TemplateHandler
         #{source}
       end
+      presenter.setup!
       if key = presenter.cache_key
         @output_buffer = ActiveSupport::SafeBuffer.new

data/lib/rails/projections.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "app/presenters/*_presenter.rb": {
+    "affinity": "controller",
+    "command": "presenter",
+    "test": "spec/presenters/%s_presenter_spec.rb",
+    "related": "app/views/%s.html.curly",
+    "template": "class %SPresenter < Curly::Presenter\nend",
+    "keywords": "presents depends_on version"
+  },
+  "app/views/*.html.curly": {
+    "affinity": "controller",
+    "test": "spec/views/%s_spec.rb",
+    "related": "app/presenters/%s_presenter.rb"
+  }
+}

data/spec/template_handler_spec.rb CHANGED Viewed

@@ -9,6 +9,10 @@ describe Curly::TemplateHandler do
         @cache_duration = options.fetch(:cache_duration, nil)
       end
+      def setup!
+        @context.content_for(:foo, "bar")
+      end
       def foo
         "FOO"
       end
@@ -47,6 +51,12 @@ describe Curly::TemplateHandler do
         @clock += duration
       end
+      def content_for(key, value = nil)
+        @contents ||= {}
+        @contents[key] = value if value.present?
+        @contents[key]
+      end
       def cache(key, options = {})
         fragment, expired_at = @cache[key]
@@ -98,6 +108,12 @@ describe Curly::TemplateHandler do
     output.should be_html_safe
   end
+  it "calls the #setup! method before rendering the view" do
+    template.stub(:source) { "{{foo}}" }
+    output
+    context.content_for(:foo).should == "bar"
+  end
   context "caching" do
     before do
       template.stub(:source) { "{{bar}}" }

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: curly-templates
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
   prerelease:
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-05-22 00:00:00.000000000 Z
+date: 2013-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -109,6 +109,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -124,6 +125,7 @@ files:
 - lib/generators/curly/controller/controller_generator.rb
 - lib/generators/curly/controller/templates/presenter.rb.erb
 - lib/generators/curly/controller/templates/view.html.curly.erb
+- lib/rails/projections.json
 - spec/compiler_spec.rb
 - spec/generators/controller_generator_spec.rb
 - spec/presenter_spec.rb
@@ -145,7 +147,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2436310145351861333
+      hash: 3268332445838018672
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: