Overview¶ ↑

Cells are like controllers in Rails - they have methods and corresponding views. However, 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!¶ ↑

To quickly create the necessary files for an example cell run the generator:

script/generate cell Article newest top_article

The generated cell class located in app/cells/article_cell.rb could look like this, after some editing:

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

The corresponding views are 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 would be in app/cells/article/top_article_v2.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¶ ↑

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.

cache :my_cached_state, Proc.new{|cell| Version.for(User.find(1)}

This would result in re-rendering the state :my_cached_state only if the version of the user instance changes.

Compatibility with other rails plugins¶ ↑

Cells uses the rails rendering code and thus stays completely compatible with (most?) plugins.

I18N¶ ↑

All of Rails’ new i18n features work with Cells. For example

t("Translate me, I'm a lonesome string in a cell state view!")

from the i18n helper can also be used in cell 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.

Engines¶ ↑

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.

Installation¶ ↑

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

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

This release is tested and runs with Rails 2.3.

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.

LICENSE¶ ↑

Copyright © 2007-2009, 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.