= Overview

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.

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 <tt>app/cells/article_cell.rb</tt> 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 <tt>app/cells/article/newest.html.erb</tt>:

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

The other view would be in <tt>app/cells/article/top_article_v2.html.haml</tt>:

  %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 <tt>app/controllers/blog_controller.rb</tt>
there could be an action
  
  class BlogController < ApplicationController
    def top_page
      ...
    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.

= 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 <tt>:my_cached_state</tt> 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 http://cells.rubyforge.org for documentation targeted at cells
newbies, including an overview of what you can do with cells and a
tutorial.

= LICENSE

Copyright (c) 2007-2009, Nick Sutterer

Copyright (c) 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.