curly-templates 0.2.1 → 0.3.0

data/Gemfile

@@ -1,4 +1,4 @@
-source :rubygems
+source 'https://rubygems.org/'
 
 gemspec
 

data/README.md

@@ -29,7 +29,7 @@ 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.2.0'
+gem 'curly-templates'
 ```
 
 
@@ -144,11 +144,24 @@ end
 Caching
 -------
 
+Caching is handled at two levels in Curly – statically and dynamically. Static caching
+concerns changes to your code and templates introduced by deploys. If you do not wish
+to clear your entire cache every time you deploy, you need a way to indicate that some
+view, helper, or other piece of logic has changed.
+
+Dynamic caching concerns changes that happen on the fly, usually made by your users in
+the running system. You wish to cache a view or a partial and have it expire whenever
+some data is updated – usually whenever a specific record is changed.
+
+
+### Dynamic Caching
+
 Because of the way logic is contained in presenters, caching entire views or partials
-becomes exceedingly straightforward. Simply define a `#cache_key` method that returns
-a non-nil object, and the return value will be used to cache the template.
+by the data they present becomes exceedingly straightforward. Simply define a
+`#cache_key` method that returns a non-nil object, and the return value will be used to
+cache the template.
 
-Whereas in ERB your would include the `cache` call in the template itself:
+Whereas in ERB you would include the `cache` call in the template itself:
 
 ```erb
 <% cache([@post, signed_in?]) do %>
@@ -182,6 +195,63 @@ end
 ```
 
 
+### Static Caching
+
+Static caching will only be enabled for presenters that define a non-nil `#cache_key`
+method (see "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:
+
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  version 3
+
+  def cache_key
+    # Some objects
+  end
+end
+```
+
+This will change the cache keys for all instances of that view, effectively expiring
+the old cache entries.
+
+This works well for views, or for partials that are rendered in views that themselves
+are not cached. If the partial is nested within a view that _is_ cached, however, the
+outer cache will not be expired. The solution is to register that the inner partial
+is a dependency of the outer one such that Curly can automatically deduce that the
+outer partial cache should be expired:
+
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  version 3
+  depends_on 'posts/comment'
+
+  def cache_key
+    # Some objects
+  end
+end
+
+class Posts::CommentPresenter < Curly::Presenter
+  version 4
+  depends_on 'posts/comment'
+
+  def cache_key
+    # Some objects
+  end
+end
+```
+
+Now, if the version of `Posts::CommentPresenter` is bumped, the cache keys for both
+presenters would change. You can register any number of view paths with `depends_on`.
+
+
+Thanks
+------
+
+Thanks to [Zendesk](http://zendesk.com/) for sponsoring the work on Curly.
+
+
 Copyright and License
 ---------------------
 

data/curly-templates.gemspec

@@ -4,15 +4,16 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
 
   s.name              = 'curly-templates'
-  s.version           = '0.2.1'
-  s.date              = '2013-02-09'
+  s.version           = '0.3.0'
+  s.date              = '2013-04-18'
 
   s.summary     = "Free your views!"
   s.description = "A view layer for your Rails apps that separates structure and logic."
+  s.license     = "apache2"
 
   s.authors  = ["Daniel Schierbeck"]
-  s.email    = 'daniel.schierbeck@gmail.com.com'
-  s.homepage = 'https://github.com/dasch/curly'
+  s.email    = 'daniel.schierbeck@gmail.com'
+  s.homepage = 'https://github.com/zendesk/curly'
 
   s.require_paths = %w[lib]
 

data/lib/curly.rb

@@ -26,7 +26,7 @@
 # See Curly::Presenter for more information on presenters.
 #
 module Curly
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 
   REFERENCE_REGEX = %r(\{\{(\w+)\}\})
 

data/lib/curly/presenter.rb

@@ -102,11 +102,91 @@ module Curly
       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
+    class << self
+
+      # 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 presenter_name_for_path(path)
+        "#{path}_presenter".camelize
+      end
+
+      def presenter_for_path(path)
+        presenter_name_for_path(path).constantize
+      end
+
+      # A list of methods available to templates rendered with the presenter.
+      #
+      # Returns an Array of Symbol method names.
+      def available_methods
+        public_instance_methods - Curly::Presenter.public_instance_methods
+      end
+
+      # The set of view paths that the presenter depends on.
+      #
+      # Example
+      #
+      #   class Posts::ShowPresenter < Curly::Presenter
+      #     version 2
+      #     depends_on 'posts/comment', 'posts/comment_form'
+      #   end
+      #
+      #   Posts::ShowPresenter.dependencies
+      #   #=> ['posts/comment', 'posts/comment_form']
+      #
+      # Returns a Set of String view paths.
+      def dependencies
+        @dependencies ||= Set.new
+      end
+
+      # Indicate that the presenter depends a list of other views.
+      #
+      # deps - A list of String view paths that the presenter depends on.
+      #
+      # Returns nothing.
+      def depends_on(*deps)
+        dependencies.merge(deps)
+      end
+
+      # Get or set the version of the presenter.
+      #
+      # version - The Integer version that should be set. If nil, no version
+      #           is set.
+      #
+      # Returns the current Integer version of the presenter.
+      def version(version = nil)
+        @version = version if version.present?
+        @version || 0
+      end
+
+      # The cache key for the presenter class. Includes all dependencies as well.
+      #
+      # Returns a String cache key.
+      def cache_key
+        @cache_key ||= compute_cache_key
+      end
+
+      private
+
+      def compute_cache_key
+        dependency_cache_keys = dependencies.map do |path|
+          presenter = presenter_for_path(path)
+          presenter.cache_key
+        end
+
+        [name, version, dependency_cache_keys].flatten.join("/")
+      end
+
+      def presents(*args)
+        self.presented_names += args
+      end
     end
 
     private
@@ -114,10 +194,6 @@ module Curly
     class_attribute :presented_names
     self.presented_names = [].freeze
 
-    def self.presents(*args)
-      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.

data/lib/curly/template_handler.rb

@@ -4,20 +4,6 @@ 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.
@@ -26,7 +12,8 @@ class Curly::TemplateHandler
   #
   # Returns a String containing the Ruby code representing the template.
   def self.call(template)
-    presenter_class = presenter_name_for_path(template.virtual_path)
+    path = template.virtual_path
+    presenter_class = Curly::Presenter.presenter_name_for_path(path)
 
     source = Curly.compile(template.source)
     template_digest = Digest::MD5.hexdigest(template.source)
@@ -52,11 +39,17 @@ class Curly::TemplateHandler
 
       template_digest = #{template_digest.inspect}
 
+      if #{presenter_class}.respond_to?(:cache_key)
+        presenter_key = #{presenter_class}.cache_key
+      else
+        presenter_key = nil
+      end
+
       options = {
         expires_in: presenter.cache_duration
       }
 
-      cache([template_digest, key], options) do
+      cache([template_digest, key, presenter_key].compact, options) do
         safe_concat(view_function.call)
       end
 

data/spec/presenter_spec.rb

@@ -24,4 +24,59 @@ describe Curly::Presenter do
     presenter.midget.should == "Meek Harolson"
     presenter.clown.should == "Bubbles"
   end
+
+  describe ".presenter_for_path" do
+    it "returns the presenter class for the given path" do
+      presenter = double("presenter")
+      stub_const("Foo::BarPresenter", presenter)
+
+      Curly::Presenter.presenter_for_path("foo/bar").should == presenter
+    end
+  end
+
+  describe ".version" do
+    it "sets the version of the presenter" do
+      presenter1 = Class.new(Curly::Presenter) do
+        version 42
+      end
+
+      presenter2 = Class.new(Curly::Presenter) do
+        version 1337
+      end
+
+      presenter1.version.should == 42
+      presenter2.version.should == 1337
+    end
+
+    it "returns 0 if no version has been set" do
+      presenter = Class.new(Curly::Presenter)
+      presenter.version.should == 0
+    end
+  end
+
+  describe ".cache_key" do
+    it "includes the presenter's class name and version" do
+      presenter = Class.new(Curly::Presenter) { version 42 }
+      stub_const("Foo::BarPresenter", presenter)
+
+      Foo::BarPresenter.cache_key.should == "Foo::BarPresenter/42"
+    end
+
+    it "includes the cache keys of presenters in the dependency list" do
+      presenter = Class.new(Curly::Presenter) do
+        version 42
+        depends_on 'foo/bum'
+      end
+
+      dependency = Class.new(Curly::Presenter) do
+        version 1337
+      end
+
+      stub_const("Foo::BarPresenter", presenter)
+      stub_const("Foo::BumPresenter", dependency)
+
+      cache_key = Foo::BarPresenter.cache_key
+      cache_key.should == "Foo::BarPresenter/42/Foo::BumPresenter/1337"
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1 +1,2 @@
 require 'active_support/all'
+require 'curly'

data/spec/template_handler_spec.rb

@@ -133,6 +133,20 @@ describe Curly::TemplateHandler do
       output.should == "FOOBAR"
     end
 
+    it "adds the presenter class' cache key to the instance's cache key" do
+      # Make sure caching is enabled
+      context.assigns[:cache_key] = "x"
+
+      presenter_class.stub(:cache_key) { "foo" }
+
+      output.should == "BAR"
+
+      presenter_class.stub(:cache_key) { "bar" }
+
+      context.stub(:bar) { "FOOBAR" }
+      output.should == "FOOBAR"
+    end
+
     it "expires the cache keys after #cache_duration" do
       context.assigns[:cache_key] = "x"
       context.assigns[:cache_duration] = 42

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: curly-templates
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-09 00:00:00.000000000 Z
+date: 2013-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -104,7 +104,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: A view layer for your Rails apps that separates structure and logic.
-email: daniel.schierbeck@gmail.com.com
+email: daniel.schierbeck@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -126,8 +126,9 @@ files:
 - spec/presenter_spec.rb
 - spec/spec_helper.rb
 - spec/template_handler_spec.rb
-homepage: https://github.com/dasch/curly
-licenses: []
+homepage: https://github.com/zendesk/curly
+licenses:
+- apache2
 post_install_message: 
 rdoc_options:
 - --charset=UTF-8
@@ -141,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2816901240336629131
+      hash: 1050384954956597031
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -150,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 2
 summary: Free your views!