cells 2.3.0

data/lib/cell/caching.rb

@@ -0,0 +1,151 @@
+# To improve performance rendered state views can be cached using Rails' caching
+# mechanism.
+# If this it configured (e.g. using our fast friend memcached) all you have to do is to 
+# tell Cells which state you want to cache. You can further attach a proc to expire the 
+# cached view.
+#
+# As always I stole a lot of code, this time from Lance Ivy <cainlevy@gmail.com> and
+# his fine components plugin at http://github.com/cainlevy/components.
+
+module Cell::Caching
+  
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      # mixin Cell::Base#cache, setup vars and extend #render_state if caching's on.
+      extend ClassMethods
+      
+      return unless cache_configured?
+      
+      alias_method_chain :render_state, :caching
+    end
+    
+    
+  end
+ 
+ 
+ 
+  module ClassMethods
+    # Activate caching for the state <tt>state</tt>. If no other options are passed
+    # the view will be cached forever.
+    #
+    # You may pass a Proc or a Symbol as cache expiration <tt>version_proc</tt>.
+    # This method is called every time the state is rendered, and is expected to return a
+    # Hash containing the cache key ingredients.
+    #
+    # Additional options will be passed directly to the cache store when caching the state.
+    # Useful for simply setting a TTL for a cached state.
+    # Note that you may omit the <tt>version_proc</tt>.
+    # 
+    # 
+    # Example:
+    #   class CachingCell < Cell::Base
+    #     cache :versioned_cached_state, Proc.new{ {:version => 0} }
+    # would result in the complete cache key
+    #   cells/CachingCell/versioned_cached_state/version=0
+    #
+    # If you provide a symbol, you can access the cell instance directly in the versioning
+    # method:
+    #
+    #   class CachingCell < Cell::Base
+    #     cache :cached_state, :my_cache_version
+    #
+    #     def my_cache_version
+    #       { :user     => current_user.id,
+    #         :item_id  => params[:item] }
+    #       }
+    #     end
+    # results in a very specific cache key, for customized caching:
+    #   cells/CachingCell/cached_state/user=18/item_id=1
+    #
+    # You may also set a TTL only, e.g. when using the memcached store:
+    #
+    #  cache :cached_state, :expires_in => 3.minutes
+    #
+    # Or use both, having a versioning proc <em>and</em> a TTL expiring the state as a fallback
+    # after a certain amount of time.
+    #
+    #  cache :cached_state, Proc.new { {:version => 0} }, :expires_in => 10.minutes
+    #--
+    ### TODO: implement for string, nil.
+    ### DISCUSS: introduce return method #sweep ? so the Proc can explicitly
+    ###   delegate re-rendering to the outside.
+    #--  
+    def cache(state, version_proc=nil, cache_opts={})
+      if version_proc.is_a?(Hash)
+        cache_opts    = version_proc
+        version_proc  = nil
+      end
+      
+      version_procs[state]  = version_proc
+      cache_options[state]  = cache_opts
+    end
+    
+    def version_procs;  @version_procs    ||= {}; end
+    def cache_options;  @cache_options    ||= {}; end
+    
+    def cache_store #:nodoc:
+      @cache_store ||= ActionController::Base.cache_store
+    end
+    
+    def cache_key_for(cell_class, state, args = {}) #:nodoc:
+      key_pieces = [cell_class, state]
+
+      args.collect{|a,b| [a.to_s, b]}.sort.each{ |k,v| key_pieces << "#{k}=#{v}" }
+      key = key_pieces.join('/')
+
+      ActiveSupport::Cache.expand_cache_key(key, :cells)
+    end
+    
+    def expire_cache_key(key, opts=nil)
+      cache_store.delete(key, opts)
+    end
+  end
+  
+  
+  
+  def render_state_with_caching(state)
+    return render_state_without_caching(state) unless state_cached?(state) 
+    
+    key = cache_key(state, call_version_proc_for_state(state))
+    ### DISCUSS: see sweep discussion at #cache.
+    
+    # cache hit:
+    if content = read_fragment(key)
+      return content 
+    end
+    # re-render:
+    return write_fragment(key, render_state_without_caching(state), cache_options[state])
+  end
+  
+  
+  def read_fragment(key, cache_options = nil) #:nodoc:
+    returning self.class.cache_store.read(key, cache_options) do |content|
+      @controller.logger.debug "Cell Cache hit: #{key}" unless content.blank?
+    end
+  end
+ 
+  def write_fragment(key, content, cache_opts = nil) #:nodoc:
+    @controller.logger.debug "Cell Cache miss: #{key}"
+    self.class.cache_store.write(key, content, cache_opts)
+    content
+  end
+  
+  # Call the versioning Proc for the respective state.
+  def call_version_proc_for_state(state)
+    version_proc = version_procs[state]
+    
+    return {} unless version_proc # call to #cache was without any args.
+    
+    return version_proc.call(self) if version_proc.kind_of? Proc
+    send(version_proc)
+  end
+  
+  def cache_key(state, args = {}) #:nodoc:
+    self.class.cache_key_for(self.cell_name, state, args)
+  end
+  
+  def state_cached?(state); self.class.version_procs.has_key?(state);  end
+  def version_procs;        self.class.version_procs;  end
+  def cache_options;        self.class.cache_options;  end
+
+end

data/lib/cell/view.rb

@@ -0,0 +1,55 @@
+module Cell
+  class View < ::ActionView::Base
+    
+    attr_accessor :cell
+    
+    alias_method :render_for, :render
+    
+    # Tries to find the passed template in view_paths. Returns the view on success-
+    # otherwise it will throw an ActionView::MissingTemplate exception.
+    def try_picking_template_for_path(template_path)
+      self.view_paths.find_template(template_path, template_format)
+    end
+    
+    ### TODO: this should just be a thin helper.
+    ### dear rails folks, could you guys please provide a helper #render and an internal #render_for
+    ### so that we can overwrite the helper and cleanly reuse the internal method? using the same 
+    ### method both internally and externally sucks ass.
+    def render(options = {}, local_assigns = {}, &block)
+      ### TODO: delegate dynamically:
+      ### TODO: we have to find out if this is a call to the cells #render method, or to the rails
+      ###       method (e.g. when rendering a layout). what a shit.
+      if view = options[:view]
+        return cell.render_view_for(options, view)
+      end
+      
+      
+      # rails compatibility we should get rid of:
+      if partial_path = options[:partial]
+        # adds the cell name to the partial name.
+        options[:partial] = expand_view_path(partial_path)
+      end
+      #throw Exception.new
+      
+      super(options, local_assigns, &block)
+    end
+    
+    
+    def expand_view_path(path)
+      path = "#{cell.cell_name}/#{path}" unless path.include?('/')  
+      path
+    end
+    
+    # this prevents cell ivars from being overwritten by same-named
+    # controller ivars.
+    # we'll hopefully get a cleaner way, or an API, to handle this in rails 3.
+    def _copy_ivars_from_controller #:nodoc:
+      if @controller
+        variables = @controller.instance_variable_names
+        variables -= @controller.protected_instance_variables if @controller.respond_to?(:protected_instance_variables)
+        variables -= assigns.keys.collect {|key| "@#{key}"} # cell ivars override controller ivars.
+        variables.each { |name| instance_variable_set(name, @controller.instance_variable_get(name)) }
+      end
+    end
+  end
+end

data/lib/cells_helper.rb

@@ -0,0 +1,49 @@
+# Sorry for the interface violations, but it looks as if there are 
+# no interfaces in rails at all.
+module CellsHelper
+
+  # Executes #capture on the global ActionView and sets <tt>name</tt> as the 
+  # instance variable name.
+  #
+  # Example:
+  #
+  #  <p>
+  #  <% global_capture :greeting do
+  #    <h1>Hi, Nick!</h1>
+  #  <% end %>
+  #
+  # The captured markup can be accessed in your global action view or in your layout.
+  #
+  #  <%= @greeting %>
+  def global_capture(name, &block)
+    global_view = controller.instance_variable_get( "@template" ) 
+    content     = capture &block
+    global_view.send("instance_variable_set", "@#{name}", content)
+  end
+  
+  
+  # Executes #content_for on the global ActionView.
+  #
+  # Example:
+  #
+  #  <p>
+  #  <% global_content_for :greetings do
+  #    <h1>Hi, Michal!</h1>
+  #  <% end %>
+  #
+  # As in global_capture, the markup can be accessed in your global action view or in your layout.
+  #
+  #  <%= yield :greetings %>
+  def global_content_for(name, content = nil, &block)
+    # OMG.
+    global_view = controller.instance_variable_get( "@template" )
+    ivar        = "@content_for_#{name}"
+    content     = capture(&block) if block_given?
+    old_content = global_view.send("instance_variable_get", ivar)
+    
+    
+    global_view.send("instance_variable_set", ivar, "#{old_content}#{content}")
+    
+    nil
+  end
+end

data/lib/rails_extensions.rb

@@ -0,0 +1,75 @@
+# The Cells plugin defines a number of new methods for ActionView::Base.  These allow
+# you to render cells from within normal controller views as well as from Cell state views.
+module Cell
+
+  module ActionView
+    # Call a cell state and return its rendered view.
+    #
+    # ERB example:
+    #   <div id="login">
+    #     <%= render_cell :user, :login_prompt, :message => "Please login" %>
+    #   </div>
+    #
+    # If you have a <tt>UserCell</tt> cell in <tt>app/cells/user_cell.rb</tt>, which has a
+    # <tt>UserCell#login_prompt</tt> method, this will call that method and then will
+    # find the view <tt>app/cells/user/login_prompt.html.erb</tt> and render it. This is 
+    # called the <tt>:login_prompt</tt> <em>state</em> in Cells terminology.
+    #
+    # If this view file looks like this:
+    #   <h1><%= @opts[:message] %></h1>
+    #   <label>name: <input name="user[name]" /></label>
+    #   <label>password: <input name="user[password]" /></label>
+    #
+    # The resulting view in the controller will be roughly equivalent to:
+    #   <div id="login">
+    #     <h1><%= "Please login" %></h1>
+    #     <label>name: <input name="user[name]" /></label>
+    #     <label>password: <input name="user[password]" /></label>
+    #   </div>
+    def render_cell(name, state, opts = {})
+      cell = Cell::Base.create_cell_for(@controller, name, opts)
+      cell.render_state(state)
+    end
+  end
+  
+  
+  # These ControllerMethods are automatically added to all Controllers when
+  # the cells plugin is loaded.
+  module ActionController
+
+    # Equivalent to ActionController#render_to_string, except it renders a cell
+    # rather than a regular templates.
+    def render_cell(name, state, opts={})
+      cell = Cell::Base.create_cell_for(self, name, opts)
+
+      return cell.render_state(state)
+    end
+    
+    alias_method :render_cell_to_string, :render_cell # just for backward compatibility.
+    
+    
+    # Expires the cached cell state view, similar to ActionController::expire_fragment.
+    # Usually, this method is used in Sweepers.
+    # Beside the obvious first two args <tt>cell_name</tt> and <tt>state</tt> you can pass
+    # in additional cache key <tt>args</tt> and cache store specific <tt>opts</tt>.
+    # 
+    # Example:
+    #
+    #  class ListSweeper < ActionController::Caching::Sweeper
+    #   observe List, Item
+    #
+    #   def after_save(record)
+    #     expire_cell_state :my_listing, :display_list
+    #   end
+    #
+    # will expire the view for state <tt>:display_list</tt> in the cell <tt>MyListingCell</tt>.
+    def expire_cell_state(cell_name, state, args={}, opts=nil)
+      key = Cell::Base.cache_key_for(cell_name, state, args)
+      Cell::Base.expire_cache_key(key, opts)
+    end
+  end
+  
+end
+
+
+

data/test/bugs_test.rb

@@ -0,0 +1,26 @@
+require File.dirname(__FILE__) + '/../../../../test/test_helper'
+require File.dirname(__FILE__) + '/testing_helper'
+
+
+class MyTestCell < Cell::Base
+  def state_with_instance_var
+    @my_ivar = "value from cell"
+    render
+  end
+end
+
+
+class CellsTest < ActionController::TestCase
+  include CellsTestMethods
+  
+  def test_controller_overriding_cell_ivars
+    @controller.class_eval do
+      attr_accessor :my_ivar
+    end
+    @controller.my_ivar = "value from controller"
+    
+    cell = MyTestCell.new(@controller)
+    c = cell.render_state(:state_with_instance_var)
+    assert_equal "value from cell", c
+  end
+end

data/test/caching_test.rb

@@ -0,0 +1,266 @@
+require File.dirname(__FILE__) + '/../../../../test/test_helper'
+require File.dirname(__FILE__) + '/testing_helper'
+
+# usually done by rails' autoloading:
+require File.dirname(__FILE__) + '/cells/test_cell'
+
+### NOTE: add 
+###   config.action_controller.cache_store = :memory_store
+###   config.action_controller.perform_caching = true
+### to config/environments/test.rb to make this tests work.
+
+class CellsCachingTest < Test::Unit::TestCase
+  include CellsTestMethods
+  
+  def setup
+    super
+    @controller.session= {}
+    @cc = CachingCell.new(@controller)
+    @c2 = AnotherCachingCell.new(@controller)
+  end
+    
+  #def self.path_to_test_views
+  #  RAILS_ROOT + "/vendor/plugins/cells/test/views/"
+  #end
+  
+  
+  def test_state_cached?
+    assert @cc.state_cached?(:cached_state)
+    assert ! @cc.state_cached?(:not_cached_state)
+  end
+  
+  def test_cache_without_options
+    # :cached_state is cached without any options:
+    assert_nil      @cc.version_procs[:cached_state]
+    assert_nil      @cc.version_procs[:not_cached_state]
+    
+    # cache_options must at least return an empty hash for a cached state:
+    assert_equal(  {},   @cc.cache_options[:cached_state])
+    assert_nil      @cc.cache_options[:not_cached_state]
+  end
+  
+  
+  def test_cache_with_proc_only
+    CachingCell.class_eval do
+      cache :my_state, Proc.new {}
+    end
+    
+    assert_kind_of  Proc, @cc.version_procs[:my_state]
+    assert_equal(   {},   @cc.cache_options[:my_state])
+  end
+  
+  
+  def test_cache_with_proc_and_cache_options
+    CachingCell.class_eval do
+      cache :my_state, Proc.new{}, {:expires_in => 10.seconds}
+    end
+    
+    assert_kind_of  Proc, @cc.version_procs[:my_state]
+    assert_equal(   {:expires_in => 10.seconds}, @cc.cache_options[:my_state])
+  end
+  
+  
+  def test_cache_with_cache_options_only
+    CachingCell.class_eval do
+      cache :my_state, :expires_in => 10.seconds
+    end
+    
+    assert          @cc.version_procs.has_key?(:my_state)
+    assert_nil      @cc.version_procs[:my_state]
+    assert_equal(   {:expires_in => 10.seconds}, @cc.cache_options[:my_state])
+  end
+  
+  
+  
+  def test_if_caching_works
+    c = @cc.render_state(:cached_state)
+    assert_equal c, "1 should remain the same forever!"
+    
+    c = @cc.render_state(:cached_state)
+    assert_equal c, "1 should remain the same forever!", ":cached_state was invoked again"
+  end
+  
+  def test_cache_key
+    assert_equal "cells/caching/some_state", @cc.cache_key(:some_state)
+    assert_equal @cc.cache_key(:some_state), Cell::Base.cache_key_for(:caching, :some_state)
+    assert_equal "cells/caching/some_state/param=9", @cc.cache_key(:some_state, :param => 9)
+    assert_equal "cells/caching/some_state/a=1/b=2", @cc.cache_key(:some_state, :b => 2, :a => 1)
+  end
+  
+  def test_render_state_without_caching
+    c = @cc.render_state(:not_cached_state)
+    assert_equal c, "i'm really static"
+    c = @cc.render_state(:not_cached_state)
+    assert_equal c, "i'm really static"
+  end
+  
+  def test_caching_with_version_proc
+    @controller.session[:version] = 0
+    # render state, as it's not cached:
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "0 should change every third call!"
+    
+    @controller.session[:version] = -1
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "0 should change every third call!"
+    
+    
+    @controller.session[:version] = 1
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "1 should change every third call!"
+    
+    
+    @controller.session[:version] = 2
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "2 should change every third call!"
+    
+    @controller.session[:version] = 3
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "3 should change every third call!"
+  end
+  
+  def test_caching_with_instance_version_proc
+    CachingCell.class_eval do
+      cache :versioned_cached_state, :my_version_proc
+    end
+    @controller.session[:version] = 0
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "0 should change every third call!" 
+    
+    @controller.session[:version] = 1
+    c = @cc.render_state(:versioned_cached_state)
+    assert_equal c, "1 should change every third call!"
+  end
+  
+  def test_caching_with_two_same_named_states
+    c = @cc.render_state(:cheers)
+    assert_equal c, "cheers!"
+    c = @c2.render_state(:cheers)
+    assert_equal c, "prost!"
+    c = @cc.render_state(:cheers)
+    assert_equal c, "cheers!"
+    c = @c2.render_state(:cheers)
+    assert_equal c, "prost!"
+  end
+
+  def test_caching_one_of_two_same_named_states
+    ### DISCUSS with drogus: the problem was that CachingCell and AnotherCachingCell keep
+    ### overwriting their version_procs, wasn't it? why don't we test that with different
+    ### version_procs in each cell?
+    @cc = CachingCell.new(@controller, :str => "foo1")
+    c = @cc.render_state(:another_state)
+    assert_equal c, "foo1"
+
+    @c2 = AnotherCachingCell.new(@controller, :str => "foo2")
+    c = @c2.render_state(:another_state)
+    assert_equal c, "foo2"
+
+    @cc = CachingCell.new(@controller, :str => "bar1")
+    c = @cc.render_state(:another_state)
+    assert_equal c, "foo1"
+
+    @c2 = AnotherCachingCell.new(@controller, :str => "bar2")
+    c = @c2.render_state(:another_state)
+    assert_equal c, "bar2"
+  end
+  
+  def test_expire_cache_key
+    k = @cc.cache_key(:cached_state)
+    @cc.render_state(:cached_state)
+    assert Cell::Base.cache_store.read(k)
+    Cell::Base.expire_cache_key(k)
+    assert ! Cell::Base.cache_store.read(k)
+    
+    # test via ActionController::expire_cell_state, which is called from Sweepers.
+    @cc.render_state(:cached_state)
+    assert Cell::Base.cache_store.read(k)
+    @controller.expire_cell_state(:caching, :cached_state)
+    assert ! Cell::Base.cache_store.read(k)
+    
+    # ..and additionally test if passing cache key args works:
+    k = @cc.cache_key(:cached_state, :more => :yes)
+    assert Cell::Base.cache_store.write(k, "test content")
+    @controller.expire_cell_state(:caching, :cached_state, :more => :yes)
+    assert ! Cell::Base.cache_store.read(k)
+  end
+  
+  
+  def test_find_family_view_for_state_with_caching
+    # test environment: --------------------------------------
+    assert_equal({}, ACell.state2view_cache)
+    
+    a = ACell.new(@controller)
+    a.class.instance_eval do
+        def cache_configured?;    false;  end
+    end
+    a.render_state :existing_view
+    # in development/test environment, no view name caching should happen, 
+    # if perform_caching is false.
+    assert_equal({}, ACell.state2view_cache)
+    
+    # production environment: --------------------------------
+    a = ACell.new(@controller)
+    a.class.instance_eval do
+        def cache_configured?;    true;   end
+    end
+    a.render_state :existing_view
+    assert ACell.state2view_cache.has_key?("existing_view/html") 
+  end
+end
+
+class CachingCell < Cell::Base
+  
+  cache :cached_state
+  
+  def cached_state
+    cnt = controller.session[:cache_count]
+    cnt ||= 0
+    cnt += 1
+    "#{cnt} should remain the same forever!"
+  end
+  
+  def not_cached_state
+    "i'm really static"
+  end
+  
+  cache :versioned_cached_state, Proc.new { |cell|
+      if (v = cell.session[:version]) > 0
+        {:version=>v}  
+      else
+        {:version=>0}; end
+    }
+  def versioned_cached_state
+    "#{session[:version].inspect} should change every third call!"
+  end
+  
+  
+  def my_version_proc
+    if (v = session[:version]) > 0
+        {:version=>v}  
+      else
+        {:version=>0}; end
+  end
+  #def cached_state_with_symbol_proc
+  #  
+  #end
+  cache :cheers
+  def cheers
+    "cheers!"
+  end
+
+  cache :another_state
+  def another_state
+    @opts[:str]
+  end
+end
+
+class AnotherCachingCell < Cell::Base
+  cache :cheers
+  def cheers
+    "prost!"
+  end
+
+  def another_state
+    @opts[:str]
+  end
+end