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

curly-templates 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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: