Overview¶ ↑

Cells are like controllers in Rails - they have methods and corresponding views. But their big advantage to controllers is their modularity: 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.

They perfectly work together with AJAX/JavaScript, but also run fine without it, Michael.

Give me code!¶ ↑

A cell class located in app/cells/article_cell.rb could look like this:

class ArticleCell < Cell::Base
  helper :my_formatting_and_escaping_helper   # you can use helpers in cell views!

  def newest
    @articles = Article.get_newest
    nil   # returning nil says "render the view named newest.html.[erb|haml|...]".
  end

  def top_article
    @article = Article.top_article
    nil
  end
end

The corresponding views would be in app/cells/article/newest.html.erb:

<h2>Hot stuff!</h2>
<ul>
<% @articles.each do |article| %>
  <li><%= article.title</li>
<% end %>
</ul>

The other view could be in app/cells/article/top_article.html.haml:

%h2
  = @article.title
  = format_and_escape(@article.text)

You already know that from controllers, don’t you? Speaking of controllers, here’s how you could plug the cells into the page. In app/controllers/blog_controller.rb there could be an action

class BlogController < ApplicationController
  def top_page
    ...
  end
end

where the rendered action view could be app/views/blog/top_page.html.erb:

<%= 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 cells and could be used on another page, too.

Caching¶ ↑

Caching uses Rails 2’s Rails.cache and stores it’s key in the format of “cells:cell_name:state”. It’s suggested you use memcache and it’ll fail gracefully without it. Caching is transparent to the end user.

All states the the model a re-called via a standard after_save rails hook. A method called update_states is added to all ActiveRecord models.

You can explicitly expire methods on a cell by calling handing in either :all, and array of symbols that represent a method, or a single symbol that represents a method:

CarCell.update_states                     # will update all the methods on the CarCell
CarCell.update_states :holdens            # will update the 'holden' method on the CarCell
CarCell.update_states [:holdens,:fords]   # will update the 'holden' and 'ford' method on the CarCell

Documentation¶ ↑

Reference documentation is found in the documentation of the Cell::Base class.

See cells.rubyforge.org for documentation targeted at cells newbies, including an overview of what you can do with cells and a tutorial.

Installation¶ ↑

To install, simply cd to your rails app directory and run

script/plugin install git://github.com/apotonick/cells.git

Add the following line to your environment.rb file:

require File.join(File.dirname(__FILE__), '../vendor/plugins/cells/boot')

If you’re using the Engines plugin from www.rails-engines.org, you should put the cells boot file after the engines one. If you’re just using Cells without Engines, you can put it right after Rails’s own boot.rb line.

If you define config.plugins in your environment, make sure to put all plugins that depend on Cells after Cells, and Cells after Engines if you’re using Engines.

Cells will only work with trunk Engines or tags/rel_2.1.0 (or a later branch or tag). This tag is available at: svn.rails-engines.org/engines/tags/rel_2.1.0

LICENSE¶ ↑

Copyright © 2007-2008, Nick Sutterer

Copyright © 2007-2008, Solide ICT by Peter Bex and Bob Leers

The MIT License

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.

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.