View Components for Rails.

Cells allow you to encapsulate parts of your page into a separate MVC component. They look and feel like controllers, can run arbitrary code in an action and render views.

While they improve your overall software architecture by abstracting logic into an encapsulated OOP instance, cells also maximise reuseability within or across projects.

Basically, cells can be rendered anywhere in your code. Most people use them in views to replace a helper/partial/filter mess, as a mailer renderer substitute or hook them to routes and completely bypass ActionController.

Since version 3.9 cells comes with two "dialects": You can still use a cell like a controller. However, the new view model "dialect" supercedes the traditional cell. It allows you to treat a cell more object-oriented while providing an alternative approach to helpers.

While the old dialect still works, we strongly recommend using a cell as a view model.

Introduced in version 3.11. This includes:

• Ability to tie into the asset pipeline (you can store cell related assets WITH the cell)
• Introduction of "concepts" allowing a completely self-contained layout

Your directory structure can now look like this:

app
├── concepts
│   ├── comment
│   │   ├── cell.rb
│   │   ├── views
│   │   │   ├── show.haml
│   │   │   ├── author.haml
│   │   ├── assets
│   │   │   ├── comment.js
│   │   │   ├── comment.css

Cells now look slightly different:

# app/concepts/comment/cell.rb
 
class Comment::Cell < Cell::Concept
  def show
    render
  end
end

To hook into the asset pipeline you'll need to register your cells in application.rb:

Gemgem::Application.configure do
  # ...
  config.cells.with_assets = %w(comment)
end

You'll also need to update application.js and application.css:

# app/assets/stylesheets/application.css
/*
...
*= require public_record
...
*/

# app/assets/javascripts/application.js

...
//= require comment
...

And to render the cell, use the following helper (call invokes show by default):

<%= concept("comment/cell", comment).call %>

Have fun!

Cells run with all Rails >= 3.0. For 2.3 support see below.

gem 'cells'

Cells are placed in app/cells.

app
├── cells
│   ├── comment_cell.rb
│   ├── comment
│   │   ├── show.haml
│   │   ├── list.haml

Creating a cell is nothing more than

rails generate cell cart show -e haml

create  app/cells/
create  app/cells/cart
create  app/cells/cart_cell.rb
create  app/cells/cart/show.html.haml
create  test/cells/cart_test.rb

That looks very familiar.

Now, render your cart. Why not put it in layouts/application.html.erb for now?

<div id="header">
  <%= render_cell :cart, :show, :user => @current_user %>

Feels like rendering a controller action. For good encapsulation we pass the current user from outside into the cell - a dependency injection.

Time to improve our cell code. Let's start with app/cells/cart_cell.rb:

class CartCell < Cell::Rails
  def show(args)
    user    = args[:user]
    @items  = user.items_in_cart

    render  # renders show.html.haml
  end
end

Is that a controller? Hell, yeah. We even got a #render method as we know it from the good ol' ActionController.

Since a plain call to #render will start rendering app/cells/cart/show.html.haml we should put some meaningful markup there.

#cart
  You have #{@items.size} items in your shopping cart.

Yes, Cells support all template types that are supported by Rails itself. Remember- it's a controller!

Yes, Cells have helpers just like controllers. If you need some specific helper, do

class CartCell < Cell::Rails
  helper MyExtraHelper

and it will be around in your cart views.

In Cells, everything template file is a view. You're still free to render views within views (aka "partial") but we just call it "view". There's no need to have two different types of views. Whenever you're tempted to render a partial, use the cells term view.

/ app/cells/comment/show.haml

%h1 All comments

%p
  = render :view => 'items'

TODO: rails g concept Song => show.haml,

In Cells 3.10 we introduce a new optional file structure integrating with Trailblazer's "concept-oriented" layout.

This new file layout makes a cell fully self-contained so it can be moved around just by grabbing one single directory.

Activate it with

class Comment::Cell
  self_contained!

  # ...
end

Now, the cell directory ideally looks like the following.

app
├── cells
│   ├── comment
│   │   ├── cell.rb
│   │   ├── views
│   │   │   ├── show.haml
│   │   │   ├── list.haml

Here, cell class and associated views are in the same self-contained comment directory.

You can use the new views directory along with leaving your cell class at app/cells/comment_cell.rb, if you fancy that.

Cells can also package their own assets like JavaScript, CoffeeScript, Sass and stylesheets. When configured, those files go directly into Rails' asset pipeline. This is a great way to clean up your assets by pushing scripts and styles into the component they belong to. It makes it so much easier to find out which files are actually involved per "widget".

Note: This feature is still experimental and the API (file name conventions, configuration, etc.) might change.

Assets per default sit in the cell's assets/ directory.

app
├── cells
│   ├── comment
│   │   ├── views
│   │   ├── ..
│   │   ├── assets
│   │   │   ├── comment.js.coffee
│   │   │   ├── comment.css.sass

Adding the assets files to the asset pipeline currently involves two steps (I know it feels a bit clumsy, but I'm sure we'll find a way to make it better soon).

1. Tell Rails that this cell provides its own self-contained assets.

   Gemgem::Application.configure do
     # ...
   
     config.cells.with_assets = %w(comment)

   This will add app/cells/comment/assets/ to the asset pipeline's paths.

2. Include the assets in application.js and application.css.sass

   In app/assets/application.js, you have to add the cell assets manually.

   //=# require comments

   Same goes into app/assets/application.css.sass.

   @import 'comments';

In future versions, we wanna improve this by automatically including cell assets and avoiding name clashes. If you have ideas, suggestions, I'd love to hear them.

Sometimes you need to render a global partial from app/views within a cell. For instance, the gmaps4rails helper depends on a global partial. While this breaks encapsulation it's still possible in cells - just add the global view path.

class MapCell < Cell::Rails
  append_view_path "app/views"

This is where OOP comes back to your view.

• Inherit code into your cells by deriving more abstract cells.
• Inherit views from parent cells.

Sometimes it is handy to reuse an existing view directory from another cell, to avoid a growing number of directories. You could derive the new cell and thus inherit the view paths.

class Comment::FormCell < CommentCell

This does not only allow view inheritance, but will also inherit all the code from CommentCell. This might not be what you want.

If you're just after inheriting the views, use ::inherit_views.

class Comment::FormCell < Cell::Rails
  inherit_views CommentCell

When rendering views in FormCell, the view directories to look for templates will be inherited.

Let render_cell take care of creating the right cell. Just configure your super-cell properly.

class LoginCell < Cell::Rails
  build do
    UnauthorizedUserCell unless logged_in?
  end

A call to

render_cell(:login, :box)

will render the configured UnauthorizedUserCell instead of the original LoginCell if the login test fails.

Cells allow you to cache per state. It's simple: the rendered result of a state method is cached and expired as you configure it.

To cache forever, don't configure anything

class CartCell < Cell::Rails
  cache :show

  def show
    render
  end

This will run #show only once, after that the rendered view comes from the cache.

Note that you can pass arbitrary options through to your cache store. Symbols are evaluated as instance methods, callable objects (e.g. lambdas) are evaluated in the cell instance context allowing you to call instance methods and access instance variables. All arguments passed to your state (e.g. via render_cell) are propagated to the block.

cache :show, :expires_in => 10.minutes

If you need dynamic options evaluated at render-time, use a lambda.

cache :show, :tags => lambda { |*args| tags }

If you don't like blocks, use instance methods instead.

class CartCell < Cell::Rails
  cache :show, :tags => :cache_tags

  def cache_tags(*args)
    # do your magic..
  end

The +:if+ option lets you define a condition. If it doesn't return a true value, caching for that state is skipped.

cache :show, :if => lambda { |*| has_changed? }

You can expand the state's cache key by appending a versioner block to the ::cache call. This way you can expire state caches yourself.

class CartCell < Cell::Rails
  cache :show do |options|
    order.id
  end

The versioner block is executed in the cell instance context, allowing you to access all stakeholder objects you need to compute a cache key. The return value is appended to the state key: "cells/cart/show/1".

As everywhere in Rails, you can also return an array.

class CartCell < Cell::Rails
  cache :show do |options|
    [id, options[:items].md5]
  end

Resulting in: "cells/cart/show/1/0ecb1360644ce665a4ef".

When caching is turned on, you might wanna see notifications. Just like a controller, Cells gives you the following notifications.

• write_fragment.action_controller for cache miss.
• read_fragment.action_controller for cache hits.

To activate notifications, include the Notifications module in your cell.

class Comment::Cell < Cell::Rails
  include Cell::Caching::Notifications

Cache configuration is inherited to derived cells.

Fragment caching is not implemented in Cells per design - Cells tries to move caching to the class layer enforcing an object-oriented design rather than cluttering your views with caching blocks.

If you need to cache a part of your view, implement that as another cell state.

If you want to test it in development, you need to put config.action_controller.perform_caching = true in development.rb to see the effect.

Another big advantage compared to monolithic controller/helper/partial piles is the ability to test your cells isolated.

So what if you wanna test the cart cell? Use the generated test/cells/cart_cell_test.rb test.

class CartCellTest < Cell::TestCase
  test "show" do
    invoke :show, :user => @user_fixture
    assert_select "#cart", "You have 3 items in your shopping cart."
  end

Don't forget to put require 'cell/test_case' in your project's test/test_helper.rb file.

Then, run your tests with

rake test:cells

That's easy, clean and strongly improves your component-driven software quality. How'd you do that with partials?

If you prefer RSpec examples, use the rspec-cells gem for specing.

it "should render the posts count" do
  render_cell(:posts, :count).should have_selector("p", :content => "4 posts!")
end

To run your specs we got a rake task, too!

rake spec:cells

View models supersede the old controller-like cells. View models feel more natural as they wrap domain models and then add decorating methods for the view.

They are also significantly faster since they don't need to copy helpers and instance variables to the view: The view model itself is the view context. That means, methods called in the view are invoked on your cell instance.

# app/cells/song_cell.rb
class SongCell < Cell::ViewModel
end

Instantiating the view model should happen in controllers and views, but you can virtually use them anywhere.

A default workflow for creating and rendering a view model looks as the following.

song = Song.find(1)

@cell = cell(:song, song).call

The #cell helper gives you an instance of the SongCell cell and wraps the song object.

The call invocation instructs the cell to render. Internally, that runs render_state(:show) per default.

You can basically invoke any method you want on that cell. Nevertheless, a view model should only expose the #show method per convention, which is reflected by the #call alias.

It is important to understand this convention: Internally, you may render multiple views, combine them, use instance methods to render and format values, and so on. Externally, exposing only one "public", rendering method defines a strong interface for your view model.

class SongCell < Cell::ViewModel
  def show
    render
  end
end

The render call will render the cell's show view.

- # app/cells/song/show.haml

%h1 #{title}

%p Written at #{composed_at}

= author_box

We strongly recommend to only invoke methods in views and not to use instance variables and locals. In a view model template (or, view), methods are called on the view model instance itself, meaning you can easily expose "helpers" by defining instance methods.

class SongCell < Cell::ViewModel
  include TimeagoHelper

  def show
    render
  end

  def composed_at
    timeago(model.created_at)
  end
end

In other words, using composed_at in the view will call SongCell#composed_at. Note that you have to include additional helpers into the class.

The #model methods lets you access the wrapped Song instance we passed into the cell when creating it.

Often, it is helpful to automatically expose some reader methods to the model. You can do that with ::property.

class SongCell < Cell::ViewModel
  include TimeagoHelper

  property :title

  # ...
end

You can now safely use #title in the view (and, in the cell class), it is delegated to model.title.

When extracting parts of your view into a partial, as we did for the author section, you're free to render additional views using #render. Again, wrap render calls in instance methods, otherwise you'll end up with too much logic in your view.

class SongCell < Cell::ViewModel
  include TimeagoHelper

  property :title

  # ...

  def author_box
    render :author # same as render view: :author
  end
end

This will simply render the author.haml template in the same context as the show view, meaning you might use helpers, again.

If in doubt, encapsulate nested parts of your view into a separate cell. You can use the #cell method in your cell to instantiate a nested cell.

Designing view models to create kickass UIs for your domain layer is discussed in 50+ pages in my upcoming book.

You don't need to pass in a model, it can also be a hash for a composition.

  cell(album, song: song, composer: album.composer)

This will create two readers in the cell for you automatically: #song and #composer.

Note that we are still working on a declarative API for compositions. It will be similar to the one found in Reform, Disposable::Twin and Representable:

  property :title, on: :song
  property :last_name, on: :composer

Cells 3.8 got rid of the ActionController dependency. This essentially means you can mount Cells to routes or use them like a Rack middleware. All you need to do is derive from Cell::Base.

class PostCell < Cell::Base
  ...
end

In your routes.rb file, mount the cell like a Rack app.

match "/posts" => proc { |env|
  [ 200, {}, [ Cell::Base.render_cell_for(:post, :show) ]]
}

ActionMailer doesn't have request object, so if you inherit from Cell::Rails you will receive an error. Cell::Base will fix that problem, but you will not be able to use any of routes inside your cells.

You can fix that with actionmailer_with_request which (suprise!) brings request object to the ActionMailer.

Cells can be used outside of Rails. A new module brought in 3.8.5 provides the Rails view "API" making it possible to use gems like the popular simple_form outside Rails!

All you need to do is providing the cell with some helpers, usually it's the polymorphic routing paths required by the gems.

module RoutingHelpers
  def musician_path(model)
    "/musicians/#{model.id}"
  end
end

Then, use the Cell::Rails::HelperAPI module and it should work fine (depending on the quality of the gem you're desiring to use).

require 'cell/base'
require "cell/rails/helper_api"
require "simple_form"

class BassistCell < Cell::Base
  include Cell::Rails::HelperAPI

  self._helpers = RoutingHelpers

  def show
    @musician = Musician.find(:first)
  end
end

Your views can now use the gem's helpers.

<%= simple_form_for @musician do |f| %>
  <%= f.input :name %>
  <%= f.button :submit %>
<% end %>

Note that this currently "only" works with Rails 3.2-4.0.

Now Rails::Engines can contribute to Cells view paths. By default, any 'app/cells' found inside any Engine is automatically included into Cells view paths. If you need to, you can customize the view paths changing/appending to the 'app/cell_views' path configuration. See the Cell::EngineIntegration for more details.

By default, generated cells inherit from Cell::Rails. If you want to change this, specify your new class name in config/application.rb:

module MyApp
  class Application < Rails::Application
    config.generators do |g|
      g.base_cell_class "ApplicationCell"
    end
  end
end

You can configure the cells path in case your cells don't reside in app/cells.

config.generators do |g|
  g.base_cell_path "app/widgets"
end

gem install cells -v 3.3.9

In order to copy the cells rake tasks to your app, run

script/generate cells_install

If you need a global #content_for use the cells-capture gem.

Cells can do more.

• No Limits. Have as many cells in your page as you need - no limitation to your render_cell calls.
• Cell Nesting. Have complex cell hierarchies as you can call render_cell within cells, too.

Go for it, you'll love it!

Copyright (c) 2007-2014, Nick Sutterer

Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers

Released under the MIT License.