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.
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 show @article = if params[:id] Article.find(param[:id]) elsif params[:article] params[:article] else Article.recent.first end # no call to render says "render the view named show.html.[erb|haml|...]". end def recent limit = params[:limit] || 3 @articles = Article.recent.all(:limit => limit) # no call to render says "render the view named recent.html.[erb|haml|...]". end def top_article @article = Article.top_article render :state => :show # uses the view for the :show state end end
The corresponding views would be in app/cells/article/recent.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/show.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's layout could be app/layouts/blog.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.
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.
To install, simply cd to your rails app directory and run
script/plugin install git://github.com/joshuabates/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
Copyright © 2008, Caring, Inc. by Christopher Eppstein and Joshua Bates
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.