Cells View Component Library

In Rails, use the cell helper in views or controllers. In any other Ruby environment, use the call style: CellClass.(@model).().

To render a specific state (method) in a cell, use the syntax cell(:name, @model).(:state).

To use Cells in a standard Ruby environment, add the cells gem to your Gemfile. For Rails integration, use the cells-rails gem.

Cells requires a template engine to render views. You must include one of the following in your Gemfile:

• cells-erb (for ERB)
• cells-hamlit (recommended replacement for Haml)
• cells-haml (requires gem "haml", github: "haml/haml", ref: "7c7c169")
• cells-slim (for Slim)

In non-Rails environments, you must explicitly include the template module in your cell class.

Cells can be tested like any other Ruby object. Since a cell returns an HTML string, you can use testing frameworks like RSpec, MiniTest, or Capybara to assert against the output.

html = CommentCell.(@comment).()
Capybara.string(html).must_have_css "h3"

To use the Cells library in your Ruby project, ensure the cell gem is installed and require it in your application entry point.

require "cell"

The Cell::Builder module allows you to instantiate different cell classes based on the model type passed to the cell helper. This enables polymorphic UI components.

class CommentCell < Cell::ViewModel
  include ::Cell::Builder

  builds do |model, options|
    case model
    when Post; PostCell
    when Comment; CommentCell
    end
  end
end

# Usage:
cell(:comment, Post.find(1)) #=> creates a PostCell.

You can define caching for specific cell states using the cache method. This ensures the state is rendered once and subsequent calls return the cached fragment. You can pass options like expires_in to the cache method.

class CommentCell < Cell::ViewModel
  cache :show, expires_in: 10.minutes
end

Use property :name to create automatic readers that delegate to the model. By default, Cells does not perform HTML escaping. To ensure property readers return escaped strings, include the Escaped module in your cell class.

class CommentCell < Cell::ViewModel
  include Escaped

  property :title
end

# song.title                 #=> "<script>Dangerous</script>"
# Comment::Cell.(song).title #=> "&lt;script&gt;Dangerous&lt;/script&gt;"

In Rails, view paths default to app/cells/ or app/concepts/. In any Ruby environment, you can manually set or append to the view paths using self.view_paths.

class CommentCell < Cell::ViewModel
  self.view_paths = "lib/views"
end

A cell is a class inheriting from Cell::ViewModel. You define properties that delegate to the model and methods that represent view states. Calling render within a method will invoke the corresponding view file.

class CommentCell < Cell::ViewModel
  property :body
  property :author

  def show
    render
  end

private
  def author_link
    link_to "#{author.email}", author
  end
end

Use Cell.Options(hash) to create a Cell::Options object from a hash of values. Each value in the hash is converted into a Cell::Option.

You can then call the resulting Options object with arguments (e.g., options.call(*args)). This evaluates every option in the collection using the provided arguments and returns a standard Ruby Hash containing the evaluated results.

Use Cell::Templates#[] to retrieve a template instance based on a list of search prefixes and a specific view name. The method searches through the provided prefixes sequentially until it finds a matching file. Once a template is found, it is cached for the duration of the process to optimize performance in production environments.

Key Behaviors:

• Prefix Search: It iterates through prefixes and returns the first template that exists at #{prefix}/#{view}.
• Caching: The result is cached per prefixes set and view name. The options hash is not considered part of the cache key.
• Custom Template Classes: You can pass a :template_class in the options hash to specify which class should be instantiated to handle the template.