cells 2.3.0 → 3.3.0

data/lib/cells/cell/caching.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+
+# 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 Cells
+  module Cell
+    module 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:
+          ::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|
+          log "Cell Cache hit: #{key}" unless content.blank?
+        end
+      end
+
+      def write_fragment(key, content, cache_opts = nil) #:nodoc:
+        log "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
+  end
+end

data/lib/cells/cell/view.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+module Cells
+  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
+end

data/lib/cells/helpers.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+module Cells
+  module Helpers
+    autoload :CaptureHelper, 'cells/helpers/capture_helper'
+  end
+end

data/lib/cells/helpers/capture_helper.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+# Sorry for the interface violations, but it looks as if there are
+# no interfaces in rails at all.
+module Cells
+  module Helpers
+    module CaptureHelper
+      # 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
+  end
+end

data/lib/cells/rails.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+require 'cells/rails/action_controller'
+require 'cells/rails/action_view'
+
+Cell::Base.class_eval do
+  helper ::ApplicationHelper if defined?(::ApplicationHelper)
+end
+
+# Add extended ActionController behaviour.
+ActionController::Base.class_eval do
+  include ::Cells::Rails::ActionController
+end
+
+# Add extended ActionView behaviour.
+ActionView::Base.class_eval do
+  include ::Cells::Rails::ActionView
+end

data/lib/cells/rails/action_controller.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+# These ControllerMethods are automatically added to all Controllers when
+# the cells plugin is loaded.
+module Cells
+  module Rails
+    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
+end

data/lib/cells/rails/action_view.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+# 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 Cells
+  module Rails
+    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
+  end
+end

data/lib/cells/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Cells
+  VERSION = '3.3.0'.freeze
+end

data/rails/init.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+require 'cells'
+
+# Tell *Rails* to load files in path:
+#
+#   * +app/cells+
+#
+ActiveSupport::Dependencies.load_paths << Rails.root.join(*%w[app cells])
+
+# Rails initialization hook.
+if defined?(Rails)
+  Rails.configuration.after_initialize do
+    initializer.loaded_plugins.each do |plugin|
+      engine_cells_dir = File.join(plugin.directory, *%w[app cells])
+
+      if plugin.engine? && File.exists?(engine_cells_dir)
+        # propagate the view- and code path of this engine-cell:
+        ::Cell::Base.view_paths << engine_cells_dir
+        ::ActiveSupport::Dependencies.load_paths << engine_cells_dir
+
+        # if a path is in +load_once_path+ it won't be reloaded between requests.
+        unless config.reload_plugins?
+          ::ActiveSupport::Dependencies.load_once_paths << engine_cells_dir
+        end
+      end
+    end
+  end
+else
+  puts "[cells:] NOTE: Rails environment not available. Running isolated."
+end

data/test/{cells → app/cells}/cells_test_one_cell.rb

@@ -1,5 +1,6 @@
-class CellsTestOneCell < Cell::Base
+# encoding: utf-8
 
+class CellsTestOneCell < ::Cell::Base
   def super_state
     @my_class = self.class.to_s
     return
@@ -16,5 +17,4 @@ class CellsTestOneCell < Cell::Base
 
   def state_with_no_view
   end
-
 end

data/test/{cells → app/cells}/cells_test_two_cell.rb

@@ -1,2 +1,4 @@
+# encoding: utf-8
+
 class CellsTestTwoCell < CellsTestOneCell
 end

data/test/{cells → app/cells}/really_module/nested_cell.rb

@@ -3,7 +3,7 @@ module NestedCell; end
 
 module ReallyModule
 
-  class NestedCell < Cell::Base
+  class NestedCell < ::Cell::Base
     def happy_state
     end
   end