cells 3.3.10 → 3.4.0.beta1

data/CHANGES

@@ -1,11 +1,3 @@
-- 3.3.10
-  * TestCase#render_cell now processes options properly.
-  * added TestCase#assigns.
-
-- 3.3.9
-  * fixed loading test_case.rb
-  * added TestCase#view_assigns
-
 - 2.3
   * ::Cell::Base#new(controller, opts={})
     We got rid of the second argument cell_name, since it was completely useless.

data/Gemfile

@@ -1,3 +1,6 @@
 source :gemcutter
+#gem "rails" , :git => "http://github.com/rails/rails.git"
+gem 'sqlite3-ruby', '1.2.5', :require => 'sqlite3'	# needed in router_test, whatever.
 
-gemspec
+gem "rails" , :path => "/home/nick/projects/rails"
+#gem "railties"

data/README.rdoc

@@ -1,150 +1,134 @@
-= Overview
+= Cells
 
-Cells are like controllers in Rails - they have methods and corresponding views.
-However, their big advantage to controllers is their <em>modularity</em>: you can have
-as many cells on a page as you want. That's as if you had multiple controllers in one 
-page, where each "controller" renders only a certain part of the page.
-As if this wasn't enough, cells are superfast and lightweight.
+<em>View Components for Rails.</em>
 
-They perfectly work together with AJAX/JavaScript, but also run fine without it,
-Michael.
+== Overview
 
-== Give me code!
+Say you're writing a Rails online shop - the shopping cart is reappearing again and again in every view. You're thinking about a clean solution for that part. A mixture of controller code, before-filters, partials and helpers?
 
-To quickly create the necessary files for an example cell run the generator:
-  
-  script/generate cell Article newest top_article
+No. That sucks. Take Cells.
 
+Cells are View Components for Rails. They look and feel like controllers. They don't have no +DoubleRenderError+. They are callable everywhere in your controllers or views. They are cacheable, testable, fast and wonderful. They bring back OOP to your view and improve your software design.
 
-The generated cell class located in <tt>app/cells/article_cell.rb</tt> could look like
-this, after some editing:
+== Installation
 
-  class ArticleCell < ::Cell::Base
-    helper :my_formatting_and_escaping_helper   # you can use helpers in cell views!
-    
-    def newest
-      @articles = Article.get_newest
-      render   # will render the view named newest.html.[erb|haml|...]".
-    end
-    
-    def top_article
-      @article = Article.top_article
-      render  :view   => :top_article_v2, # renders top_article_v2.html.[erb|haml|...]
-              :layout => :box             # and put it in the layout "box.html".
-    end
-  end
+It's a gem!
 
-The corresponding views are in <tt>app/cells/article/newest.html.erb</tt>:
+Rails 3:
 
-  <h2>Hot stuff!</h2>
-  <ul>
-  <% @articles.each do |article| %>
-    <li><%= article.title %></li>
-  <% end %>
-  </ul>
+  gem install cells
 
-The other view would be in <tt>app/cells/article/top_article_v2.html.haml</tt>:
+Rails 2.3:
 
-  %h2
-    = @article.title
-    = format_and_escape(@article.text)
+  gem install cells --version 3.3.4
 
-You already know that from controllers, don't you? Speaking of controllers, here's
-how you could plug the cells into the page. In <tt>app/controllers/blog_controller.rb</tt>
-there could be an action
-  
-  class BlogController < ApplicationController
-    def top_page
-      ...
+
+== Generate
+
+Creating a cell is nothing more than
+
+  $ rails generate cell ShoppingCart display
+    create  app/cells/
+    create  app/cells/shopping_cart
+    create  app/cells/shopping_cart_cell.rb
+    create  app/cells/shopping_cart/display.html.erb
+    create  test/cells/shopping_cart_test.rb
+
+That looks very familiar.
+
+== Render the cell
+
+Now, render your cart. Why not put it in <tt>layouts/application.html.erb</tt> for now? 
+
+  <div id="header">
+    <%= render_cell :shopping_cart, :display, :user => @current_user %>
+
+Feels like rendering a controller action. As additional encapsulation we pass the current +user+ from outside. Call it knowledge hiding.
+
+== Code
+
+Time to improve our cell code. Let's start with <tt>app/cells/shopping_cart_cell.rb</tt>:
+
+  class ShoppingCartCell < Cell::Rails 
+    def display 
+      @items = @opts[:user].items_in_cart
+      
+      render  # renders display.html.erb
     end
   end
 
-where the rendered action view could be <tt>app/views/blog/top_page.html.erb</tt>:
-  
-  <%= yield %>
-  
-  <div><%= render_cell(:article, :newest) %></div>
-  <div><%= render_cell(:article, :top_article) %></div>
-    
-The "top page" would consist of the controller action's content, and two additional 
-independent boxes with interesting content. These two boxes are <em>cells</em> and could
-be used on another page, too.
+Is that a controller? Hell, yeah. We even got a +render+ method as we know it from the good ol' +ActionController+.
 
-= Caching
 
-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 for deciding
-versions or to instruct re-rendering.
+== Views
 
-  cache :my_cached_state, Proc.new{|cell| Version.for(User.find(1)}
+Since a plain call to +render+ will start rendering <tt>app/cells/shopping_cart/display.html.erb</tt> we should put some meaningful markup there.
 
-This would result in re-rendering the state <tt>:my_cached_state</tt> only if the
-version of the user instance changes. 
+  <div id="cart">
+    You have <%= @items.size %> items in your shopping cart. 
+  </div>
+  
+=== Haml? Builder?
 
-= Compatibility with other rails plugins
+Yes, Cells support all template types that are supported by Rails itself. Remember- it's a controller!
 
-Cells uses the rails rendering code and thus stays completely compatible with (most?) plugins.
+=== Helpers
 
-=== I18N
+Yes, Cells have helpers just like controllers. If you need some specific helper, do
 
-All of Rails' new i18n features work with Cells. For example
+  class ShoppingCartCell < Cell::Rails 
+    helper MyExtraHelper
 
-  t("Translate me, I'm a lonesome string in a cell state view!")
-  
-from the i18n helper can also be used in cell views. 
+and it will be around in your cart views.
 
-=== Haml
 
-Alternative templating engines will work seamlessly with Cells, too. Usem the markup language 
-of your choice (.erb, .haml, ...) to write your cell views.
+== Caching
 
-=== Engines
+Cells do strict view caching. No cluttered fragment caching. Add
 
-You can even put cells in plugins and thus maximize the modularity of your code.
-As soon as the plugin has an app/cells/ directory your cells will be added automatically
-and can be used everywhere in your application.
+  class ShoppingCartCell < Cell::Rails 
+    cache :display, :expires_in => 10.minutes
 
-= Installation
+and your cart will be re-rendered after 10 minutes.
 
-To install, simply cd to your rails app directory and run
+There are multiple advanced options for expiring your view caches, including an expiration lambda.
+
+  class ShoppingCartCell < Cell::Rails 
+    cache :display do |cell|
+      Item.still_valid?
+    end
 
-  script/plugin install git://github.com/apotonick/cells.git
-  
-This release is tested and runs with Rails 2.3.
 
+== Testing
 
-= Documentation
+Another big advantage compared to monolithic controller/helper/partial piles is the ability to test your cells isolated.
 
-Reference documentation is found in the documentation of the ::Cell::Base class.
+So what if you wanna test the cart cell? Use the generated <tt>test/cells/shopping_cart_test.rb</tt> test.
 
-See http://cells.rubyforge.org for documentation targeted at cells
-newbies, including an overview of what you can do with cells and a
-tutorial.
+  class ShoppingCartTest < ActionController::TestCase
+    include Cells::AssertionsHelper
+    
+    test "display" do
+      html = render_cell(:shopping_cart, :diplay, :user => @user_fixture)
+      assert_selekt html, "#cart", "You have 3 items in your shopping cart."
 
-= LICENSE
+That's easy, clean and strongly improves your component-driven software quality. How'd you do that with partials?
 
-Copyright (c) 2007-2009, Nick Sutterer
 
-Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
+== More features
 
-The MIT License
+Cells can do more.
+  
+<b>View Inheritance</b>::  Inherit view files dynamically from parent cells.
+<b>Cell Nesting</b>:: Have complex cell hierarchies as you can call +render_cell+ within cells, too. 
+
+Go for it, you'll love it!
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+== LICENSE
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+Copyright (c) 2007-2010, Nick Sutterer
+
+Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
 
+Released under the MIT License.

data/Rakefile

@@ -1,8 +1,4 @@
 # encoding: utf-8
-
-require 'bundler'
-Bundler::GemHelper.install_tasks
-
 require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'

data/lib/cell.rb

@@ -1,9 +1,8 @@
-require 'cells'
+# encoding: utf-8
 
-# Make cell class interface leaner, i.e. ::Cell::Base < ::Cells::Cell::Base, etc.
-# Note: Reason for doing like so is to make load path-resolving complexity to a minimum.
-#
 module Cell
-  Base = ::Cells::Cell::Base
-  View = ::Cells::Cell::View
+  #autoload :Base, 'cell/base'
+  autoload :View, 'cell/view'
+  autoload :Caching, 'cell/caching'
+  autoload :ActiveHelper, 'cell/active_helper'
 end

data/lib/{cells/cell → cell}/active_helper.rb

@@ -1,4 +1,4 @@
-module Cells::Cell::ActiveHelper
+module Cell::ActiveHelper
   
   def self.included(base)
     base.extend ClassMethods

data/lib/cell/base.rb

@@ -0,0 +1,134 @@
+    # == Basic overview
+    #
+    # A Cell is the central notion of the cells plugin.  A cell acts as a
+    # lightweight controller in the sense that it will assign variables and
+    # render a view.  Cells can be rendered from other cells as well as from
+    # regular controllers and views (see ActionView::Base#render_cell and
+    # ControllerMethods#render_cell)
+    #
+    # == A render_cell() cycle
+    #
+    # A typical <tt>render_cell</tt> state rendering cycle looks like this:
+    #   render_cell :blog, :newest_article, {...}
+    # - an instance of the class <tt>BlogCell</tt> is created, and a hash containing
+    #   arbitrary parameters is passed
+    # - the <em>state method</em> <tt>newest_article</tt> is executed and assigns instance
+    #   variables to be used in the view
+    # - Usually the state method will call #render and return
+    # - #render will retrieve the corresponding view
+    #   (e.g. <tt>app/cells/blog/newest_article.html. [erb|haml|...]</tt>),
+    #   renders this template and returns the markup.
+    #
+    # == Design Principles
+    # A cell is a completely autonomous object and it should not know or have to know
+    # from what controller it is being rendered.  For this reason, the controller's
+    # instance variables and params hash are not directly available from the cell or
+    # its views. This is not a bug, this is a feature!  It means cells are truly
+    # reusable components which can be plugged in at any point in your application
+    # without having to think about what information is available at that point.
+    # When rendering a cell, you can explicitly pass variables to the cell in the
+    # extra opts argument hash, just like you would pass locals in partials.
+    # This hash is then available inside the cell as the @opts instance variable.
+    #
+    # == Directory hierarchy
+    #
+    # To get started creating your own cells, you can simply create a new directory
+    # structure under your <tt>app</tt> directory called <tt>cells</tt>.  Cells are
+    # ruby classes which end in the name Cell.  So for example, if you have a
+    # cell which manages all user information, it would be called <tt>UserCell</tt>.
+    # A cell which manages a shopping cart could be called <tt>ShoppingCartCell</tt>.
+    #
+    # The directory structure of this example would look like this:
+    #   app/
+    #     models/
+    #       ..
+    #     views/
+    #       ..
+    #     helpers/
+    #       application_helper.rb
+    #       product_helper.rb
+    #       ..
+    #     controllers/
+    #       ..
+    #     cells/
+    #       shopping_cart_cell.rb
+    #       shopping_cart/
+    #         status.html.erb
+    #         product_list.html.erb
+    #         empty_prompt.html.erb
+    #       user_cell.rb
+    #       user/
+    #         login.html.erb
+    #       layouts/
+    #         box.html.erb
+    #     ..
+    #
+    # The directory with the same name as the cell contains views for the
+    # cell's <em>states</em>.  A state is an executed method along with a
+    # rendered view, resulting in content. This means that states are to
+    # cells as actions are to controllers, so each state has its own view.
+    # The use of partials is deprecated with cells, it is better to just
+    # render a different state on the same cell (which also works recursively).
+    #
+    # Anyway, <tt>render :partial </tt> in a cell view will work, if the
+    # partial is contained in the cell's view directory.
+    #
+    # As can be seen above, Cells also can make use of helpers.  All Cells
+    # include ApplicationHelper by default, but you can add additional helpers
+    # as well with the ::Cell::Base.helper class method:
+    #   class ShoppingCartCell < ::Cell::Base
+    #     helper :product
+    #     ...
+    #   end
+    #
+    # This will make the <tt>ProductHelper</tt> from <tt>app/helpers/product_helper.rb</tt>
+    # available from all state views from our <tt>ShoppingCartCell</tt>.
+    #
+    # == Cell inheritance
+    #
+    # Unlike controllers, Cells can form a class hierarchy.  When a cell class
+    # is inherited by another cell class, its states are inherited as regular
+    # methods are, but also its views are inherited.  Whenever a view is looked up,
+    # the view finder first looks for a file in the directory belonging to the
+    # current cell class, but if this is not found in the application or any
+    # engine, the superclass' directory is checked.  This continues all the
+    # way up until it stops at ::Cell::Base.
+    #
+    # For instance, when you have two cells:
+    #   class MenuCell < ::Cell::Base
+    #     def show
+    #     end
+    #
+    #     def edit
+    #     end
+    #   end
+    #
+    #   class MainMenuCell < MenuCell
+    #     .. # no need to redefine show/edit if they do the same!
+    #   end
+    # and the following directory structure in <tt>app/cells</tt>:
+    #   app/cells/
+    #     menu/
+    #       show.html.erb
+    #       edit.html.erb
+    #     main_menu/
+    #       show.html.erb
+    # then when you call
+    #   render_cell :main_menu, :show
+    # the main menu specific show.html.erb (<tt>app/cells/main_menu/show.html.erb</tt>)
+    # is rendered, but when you call
+    #   render_cell :main_menu, :edit
+    # cells notices that the main menu does not have a specific view for the
+    # <tt>edit</tt> state, so it will render the view for the parent class,
+    # <tt>app/cells/menu/edit.html.erb</tt>
+    #
+    #
+    # == Gettext support
+    #
+    # Cells support gettext, just name your views accordingly. It works exactly equivalent
+    # to controller views.
+    #
+    #   cells/user/user_form.html.erb
+    #   cells/user/user_form_de.html.erb
+    #
+    # If gettext is set to DE_de, the latter view will be chosen.

data/lib/cell/base_methods.rb

@@ -0,0 +1,100 @@
+module Cell
+  module BaseMethods
+    def self.included(base)
+      base.extend ClassMethods
+      
+      ### DISCUSS: move that to Rails?
+      base.class_attribute :default_template_format
+      base.default_template_format = :html
+    end
+    
+    module ClassMethods
+      def render_cell_for(controller, name, state, opts={})
+        create_cell_for(controller, name, opts).render_state(state) # FIXME: don't let BaseMethods know about controller's API.
+      end
+      
+      # Creates a cell instance of the class <tt>name</tt>Cell, passing through
+      # <tt>opts</tt>.
+      def create_cell_for(controller, name, opts={})
+        #class_from_cell_name(name).new(controller, opts)
+        class_from_cell_name(name).new(controller, opts)
+      end
+      
+      # Return the default view for the given state on this cell subclass.
+      # This is a file with the name of the state under a directory with the
+      # name of the cell followed by a template extension.
+      def view_for_state(state)
+        "#{cell_name}/#{state}"
+      end
+
+      # Find a possible template for a cell's current state.  It tries to find a
+      # template file with the name of the state under a subdirectory
+      # with the name of the cell under the <tt>app/cells</tt> directory.
+      # If this file cannot be found, it will try to call this method on
+      # the superclass.  This way you only have to write a state template
+      # once when a more specific cell does not need to change anything in
+      # that view.
+      def find_class_view_for_state(state)
+        return [view_for_state(state)] unless superclass.respond_to?(:find_class_view_for_state)
+
+        superclass.find_class_view_for_state(state) << view_for_state(state)
+      end
+
+      # Get the name of this cell's class as an underscored string,
+      # with _cell removed.
+      #
+      # Example:
+      #  UserCell.cell_name
+      #  => "user"
+      def cell_name
+        name.underscore.sub(/_cell$/, '')
+      end
+      
+      def class_from_cell_name(cell_name)
+        "#{cell_name}_cell".classify.constantize
+      end
+    end
+    
+    
+    
+    
+    
+    attr_accessor :controller
+    attr_reader   :state_name
+
+    def initialize(options={})
+      #@controller = controller
+      @opts       = options
+    end
+
+    def cell_name
+      self.class.cell_name
+    end
+
+    # Invoke the state method and render the given state.
+    def render_state(state, controller=nil)
+      @cell       = self
+      @state_name = state
+
+      dispatch_state(state)
+    end
+
+    # Call the state method.
+    def dispatch_state(state)
+      send(state)
+    end
+    
+    # Find possible files that belong to the state.  This first tries the cell's
+    # <tt>#view_for_state</tt> method and if that returns a true value, it
+    # will accept that value as a string and interpret it as a pathname for
+    # the view file. If it returns a falsy value, it will call the Cell's class
+    # method find_class_view_for_state to determine the file to check.
+    #
+    # You can override the ::Cell::Base#view_for_state method for a particular
+    # cell if you wish to make it decide dynamically what file to render.
+    def possible_paths_for_state(state)
+      self.class.find_class_view_for_state(state).reverse!
+    end
+      
+  end
+end