cells 4.0.0.rc1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c08042fbea7ac33f3607605e1e290c0956b4312
-  data.tar.gz: 017db4d48f5a0eaab84f4ecb8fc014b9470f21f0
+  metadata.gz: 22c7de3a30ac46478e9d4f4ef37c4b8fe1b49b17
+  data.tar.gz: 00b8a25633e2495ff4368ffe53e0c8f404ba7d8d
 SHA512:
-  metadata.gz: 841380b7a18d52879c7f0323816cf78bec726d520478c55a52d8366fc9706974440572e96a1fa6298daa4a056c22f720a359c1e637a2df2c6547f40c3c34c021
-  data.tar.gz: da654a5b2dceec48cab59f4b89f3c40a9e2b326bc92d0040d1ccbcac0361ec91b7756501fd21dfdb612484b1453fde248925772cf3771eed61bc26ec083441d3
+  metadata.gz: 991d17fcb0eae9e9261a6f978651601eb2e99053ac95dc5a3621054ccfaf6ebb0003fb628b8d6a974bc6f8af668ba82a9d7de2f66c80f33454f070301bf87efc
+  data.tar.gz: 9cc7f11fe2703b49721d3a222637d48f13ace7323d7399e876e04e3c43b688fff1419de2c586b01cc342addcedb16f638325590efd76378578114f3e56704ae9

data/CHANGES.md

@@ -1,10 +1,10 @@
 ## 4.0.0
 
-* **Rails Support:** Rails 3.2+ is fully supported, in older versions some form helpers do not work. Let us know if you need this.
+* **Rails Support:** Rails 4.0+ is fully supported, in older versions some form helpers do not work. Let us know how you fixed this.
 * **State args:** View models don't use state args. Options are passed into the constructor and saved there. That means that caching callbacks no longer receive arguments as everything is available via the instance itself.
 * `ViewModel.new(song: song)` won't automatically create a reader `#song`. You have to configure the cell to use a Struct twin {TODO: document}
-* **HTML Escaping:** Output is only escaped once, when using a reader method _in the view_. This highly speeds up rendering and removes the need to use `html_safe` on every string in the stack.
-* **Template Engines:** There's now _one_ template engine (e.g. ERB or HAML) per cell class. It can be set using `ViewModel::template_engine=`. In 99.9% of all cases a single application uses one single template engine application-wide, there's no need to manage code and waste lookup time for two alternative engines within one cell.
+* **HTML Escaping:** Escaping only happens for defined `property`s when `Escaped` is included.
+* **Template Engines:** There's now _one_ template engine (e.g. ERB or HAML) per cell class. It can be set by including the respective module (e.g. `Cell::Erb`) into the cell class. This happens automatically in Rails.
 * **File Naming**. The default filename just uses the engine suffix, e.g. `show.haml`. If you have two different engine formats (e.g. `show.haml` and `show.erb`), use the `format:` option: `render format: :erb`.
     If you need to render a specific mime type, provide the filename: `render view: "show.html"`.
 * Builder blocks are no longer executed in controller context but in the context they were defined. This is to remove any dependencies to the controller. If you need e.g. `params`, pass them into the `#cell(..)` call.
@@ -13,10 +13,13 @@
 ### Removed
 
 * `Cell::Rails` and `Cell::Base` got removed. Every cell is `ViewModel` or `Concept` now.
+* All methods from `AbstractController` are gone. This might give you trouble in case you were using `helper_method`. You don't need this anymore - every method included in the cell class is a "helper" in the view (it's one and the same method call).
 
-### Internals
 
-* When using HAML, we do not use any of HAML's helper hacks to "fix" ActionView and XSS. While you might not note this, it removes tons of code from our stack.
+## 4.0.0.rc2
+
+* Include `#protect_from_forgery?` into Rails cells. It returns false currently.
+* Fix `Concept#cell` which now instantiates a cell, not a concept cell.
 
 ## 4.0.0.rc1
 

data/README.md

@@ -6,7 +6,7 @@
 
 Cells allow you to encapsulate parts of your UI into components into _view models_. View models, or cells, are simple ruby classes that can render templates.
 
-Nevertheless, a cell gives you more than just a template renderer. They allow proper OOP, polymorphic builders, nesting, view inheritance, using Rails helpers, [asset packaging](http://trailblazerb.org/gems/cells/rails.html#asset-pipeline) to bundle JS, CSS or images, simple distribution via gems or Rails engines, encapsulated testing, [caching](#caching), and [integrate with Trailblazer](#concept-cells).
+Nevertheless, a cell gives you more than just a template renderer. They allow proper OOP, polymorphic builders, [nesting](#nested-cells), view inheritance, using Rails helpers, [asset packaging](http://trailblazerb.org/gems/cells/rails.html#asset-pipeline) to bundle JS, CSS or images, simple distribution via gems or Rails engines, encapsulated testing, [caching](#caching), and [integrate with Trailblazer](#concept-cells).
 
 ## This is not Cells 3.x!
 
@@ -34,8 +34,8 @@ In Rails you have the same helper API for views and controllers.
 ```ruby
 class DasboardController < ApplicationController
   def dashboard
-    @comments = cell(:comment, Comment.recent).()
-    @traffic  = cell(:report, TrafficReport.find(1))
+    @comments = cell(:comment, collection: Comment.recent)
+    @traffic  = cell(:report, TrafficReport.find(1)).()
   end
 ```
 
@@ -140,6 +140,37 @@ It is completely up to you how you test, whether it's RSpec, MiniTest or whateve
 
 [In Rails, there's support](http://trailblazerb.org/gems/cells/testing.html) for TestUnit, MiniTest and RSpec available, along with Capybara integration.
 
+## Properties
+
+The cell's model is available via the `model` reader. You can have automatic readers to the model's fields by uing `::property`.
+
+```ruby
+class CommentCell < Cell::ViewModel
+  property :author # delegates to model.author
+
+  def author_link
+    link_to author.name, author
+  end
+end
+```
+
+## HTML Escaping
+
+Cells per default does no HTML escaping, anywhere. Include `Escaped` to make property readers return escaped strings.
+
+```ruby
+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;
+```
+
+Properties and escaping are [documented here](http://trailblazerb.org/gems/cells/api.html#html-escaping).
+
 ## Installation
 
 Cells run with all Rails >= 4.0. Lower versions of Rails will still run with Cells, but you will get in trouble with the helpers.
@@ -153,7 +184,7 @@ gem 'cells', "~> 4.0.0"
 Various template engines are supported but need to be added to your Gemfile.
 
 * [cells-erb](https://github.com/trailblazer/cells-erb)
-* [cells-haml](https://github.com/trailblazer/cells-haml)
+* [cells-haml](https://github.com/trailblazer/cells-haml) Make sure to bundle Haml 4.1: `gem "haml", github: "haml/haml", ref: "7c7c169"`.
 * [cells-slim](https://github.com/trailblazer/cells-slim)
 
 ```ruby
@@ -168,6 +199,21 @@ class CommentCell < Cell::ViewModel
 end
 ```
 
+## Generators
+
+In Rails, you can generate cells and concept cells.
+
+```shell
+rails generate cell comment
+```
+
+Or.
+
+```shell
+rails generate concept comment
+```
+
+
 ## Concept Cells
 
 To have real self-contained cells you should use the new _concept cell_ which follows the [Trailblazer](http://trailblazerb.org) naming style. Concept cells need to be derived from `Cell::Concept`, sit in a namespace and are usually named `Cell`.
@@ -254,268 +300,125 @@ Cells can easily ship with their own JavaScript, CSS and more and be part of Rai
 
 ## Render API
 
-## Nested Cells
-
-Cells love to render. You can render as many views as you need in a cell state or view.
-
-```ruby
-<%= render :index %>
-```
-
-The `#render` method really just returns the rendered template string, allowing you all kind of modification.
+Unlike Rails, the `#render` method only provides a handful of options you gotta learn.
 
 ```ruby
 def show
-  render + render(:additional)
-end
-```
-
-You can even render other cells _within_ a cell using the exact same API.
-
-```ruby
-def about
-  cell(:profile, model.author).()
+  render
 end
 ```
 
-This works both in cell views and on the instance, in states.
-
+Without options, this will render the state name, e.g. `show.erb`.
 
-## Collections
-
-In order to render collections, Cells comes with a shortcut.
+You can provide a view name manually. The following calls are identical.
 
 ```ruby
-comments = Comment.all #=> three comments.
-cell(:comment, collection: comments)
+render :index
+render view: :index
 ```
 
-This will invoke `cell(:comment, song).()` three times and concatenate the rendered output automatically. In case you don't want `show` but another state rendered, use `:method`.
+If you need locals, pass them to `#render`.
 
 ```ruby
-cell(:comment, collection: comments, method: :list)
+render locals: {style: "border: solid;"}
 ```
 
-Note that you _don't_ need to invoke call here, the `:collection` behavior internally handles that for you.
+## Layouts
 
-Additional options are passed to every cell constructor.
+Every view can be wrapped by a layout. Either pass it when rendering.
 
 ```ruby
-cell(:comment, collection: comments, style: "awesome", volume: "loud")
+render layout: :default
 ```
 
-## Caching
-
-For every cell class you can define caching per state. Without any configuration the cell will run and render the state once. In following invocations, the cached fragment is returned.
+Or configure it on the class-level.
 
 ```ruby
 class CommentCell < Cell::ViewModel
-  cache :show
-
-  # ..
-end
-```
-
-The `::cache` method will forward options to the caching engine.
-
-```ruby
-cache :show, expires_in: 10.minutes
-```
-
-You can also compute your own cache key, use dynamic keys, cache tags, and so on.
-
-```ruby
-cache :show { |model, options| "comment/#{model.id}/#{model.updated_at}" }
-cache :show, :if => lambda { |*| has_changed? }
-cache :show, :tags: lambda { |model, options| "comment-#{model.id}" }
+  layout :default
 ```
 
-Caching is documented [here](http://trailblazerb.org/gems/cells/caching.html) and in chapter 8 of the [Trailblazer book](http://leanpub.com/trailblazer).
-
-
----------------------------------------
-
- This is available via the `model` method. Declarative `::property`s give you readers to the model.
-
-
-Cells allow you to encapsulate parts of your page into separate MVC components. These components are called _view models_.
-
-You can render view models anywhere in your code. Mostly, cells are used in views to replace a helper/partial/filter mess, as a mailer renderer substitute or they get hooked to routes to completely bypass `ActionController`.
-
-As you have already noticed we use _cell_ and _view model_ interchangeably here.
+The layout is treated as a view and will be searched in the same directories.
 
 
-## The Book
-
-Cells is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy my book](https://leanpub.com/trailblazer) to support the development and to learn all the cool stuff about Cells. The book discusses the following.
-
-<a href="https://leanpub.com/trailblazer">
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
-</a>
-
-* Basic view models, replacing helpers, and how to structure your view into cell components (chapter 2 and 4).
-* Advanced Cells API (chapter 4 and 6).
-* Testing Cells (chapter 4 and 6).
-* Cells Pagination with AJAX (chapter 6).
-* View Caching and Expiring (chapter 7).
-
-More chapters are coming.
-
-The book picks up where the README leaves off. Go grab a copy and support us - it talks about object- and view design and covers all aspects of the API.
-
-## No ActionView
-
-Starting with Cells 4.0 we no longer use `ActionView` as a template engine. Removing this jurassic dependency cuts down Cells' rendering code to less than 50 lines and improves rendering speed by 300%!
-
-**Note for Cells 3.x:** This README only documents Cells 4.0. Please [read the old README if you're using Cells 3.x](https://github.com/apotonick/cells/tree/31f6ed82b87b3f92613698442fae6fd61cc16de9#cells).
-
-
-## Installation
+## Nested Cells
 
-Cells run with all Rails >= 3.2. Lower versions of Rails will still run with Cells, but you will get in trouble with the helpers.
+Cells love to render. You can render as many views as you need in a cell state or view.
 
 ```ruby
-gem 'cells', "~> 4.0.0"
+<%= render :index %>
 ```
 
-## Prerequisites
-
-Cells comes bundled with ERB support. To render HAML, you have to include the [cells-haml](https://github.com/trailblazer/cells-haml) gem. The same for [cells-slim](https://github.com/trailblazer/cells-slim). Currently, they are only available as github dependencies, they will be released soon (early 2015).
+The `#render` method really just returns the rendered template string, allowing you all kind of modification.
 
 ```ruby
-gem "cells-haml", github: 'trailblazer/cells-haml'
-```
-
-The template engine extensions fix severe bugs in combination with Rails helpers and the respective engine. Time will tell if we can convince the template teams to merge these fixes.
-
-
-
-## Generate
-
-Use the bundled generator to set up a cell.
-
-```shell
-rails generate cell comment
-```
-
-```
-create  app/cells/
-create  app/cells/comment
-create  app/cells/comment_cell.rb
-create  app/cells/comment/show.erb
-```
-
-
-
-Cells provides you the view _model_ via the `#model` method. Here, this returns the `Comment` instance passed into the constructor.
-
-Of course, this view is a mess and needs be get cleaned up!
-
-## Logicless Views
-
-This is how a typical view looks in a view model.
-
-```haml
--# app/cells/comment/show.haml
-
-%h1 Comment
-
-= body
-By
-= author_link
+def show
+  render + render(:additional)
+end
 ```
 
-The methods we call in the view now need to be defined in the cell instance.
+You can even render other cells _within_ a cell using the exact same API.
 
 ```ruby
-class CommentCell < Cell::ViewModel
-  def show
-    render
-  end
-
-private
-
-  def body
-    model.body
-  end
-
-  def author_link
-    link_to model.author.name, model.author
-  end
+def about
+  cell(:profile, model.author).()
 end
 ```
 
-See how you can use helpers in a cell instance?
-
-## No Helpers
-
-The difference to conventional Rails views is that every method called in a view is directly called on the cell instance. The cell instance _is_ the rendering context. This allows a very object-oriented and clean way to implement views.
-
-Helpers as known from conventional Rails where methods and variables get copied between view and controller no longer exist in Cells.
+This works both in cell views and on the instance, in states.
 
-Note that you can still use helpers like `link_to` and all the other friends - you have to _include_ them into the cell class, though.
 
-## Automatic Properties
+## View Inheritance
 
-Often, as in the `#body` method, you simply need to delegate properties from the model. This can be done automatically using `::property`.
+Cells can inherit code from each other with Ruby's inheritance.
 
 ```ruby
 class CommentCell < Cell::ViewModel
-  def show
-    render
-  end
-
-private
-  property :body
-  property :author
+end
 
-  def author_link
-    link_to author.name, author
-  end
+class PostCell < CommentCell
 end
 ```
 
-Readers are automatically created when defined with `::property`.
-
-
-## Render
-
-multiple times allowed
-:view
-:format ".html"
-template_engine
-view_paths
+Even cooler, `PostCell` will now inherit views from `CommentCell`.
 
+```ruby
+PostCell.prefixes #=> ["app/cells/post", "app/cells/comment"]
+```
 
+When views can be found in the local `post` directory, they will be looked up in `comment`. This starts to become helpful when using [composed cells](#nested-cells).
 
+If you only want to inherit views, not the entire class, use `::inherit_views`.
 
+```ruby
+class PostCell < Cell::ViewModel
+  inherit_views Comment::Cell
+end
 
+PostCell.prefixes #=> ["app/cells/post", "app/cells/comment"]
+```
 
 ## Collections
 
-You can render a collection of models where each item is rendered using a cell.
+In order to render collections, Cells comes with a shortcut.
 
 ```ruby
-= cell(:song, collection: Song.all)
+comments = Comment.all #=> three comments.
+cell(:comment, collection: comments)
 ```
 
-Note that there is no `.call` needed. This is identical to the following snippet.
+This will invoke `cell(:comment, song).()` three times and concatenate the rendered output automatically. In case you don't want `show` but another state rendered, use `:method`.
 
 ```ruby
-- Song.all.each do |song|
-  = cell(:song, song).call(:show)
+cell(:comment, collection: comments, method: :list)
 ```
 
-Options are passed to every cell.
-
-```ruby
-= cell(:song, collection: Song.all, genre: "Heavy Metal", user: current_user)
-```
+Note that you _don't_ need to invoke call here, the `:collection` behavior internally handles that for you.
 
-The collection invocation per default calls `#show`. Use `:method` if you need another method to be called.
+Additional options are passed to every cell constructor.
 
 ```ruby
-= cell(:song, collection: Song.all, method: :detail)
+cell(:comment, collection: comments, style: "awesome", volume: "loud")
 ```
 
 ## Builder
@@ -525,255 +428,74 @@ Often, it is good practice to replace decider code from views or classes into se
 Builders allow instantiating different cell classes for different models and options.
 
 ```ruby
-class SongCell < Cell::ViewModel
+class CommentCell < Cell::ViewModel
   builds do |model, options|
-    HitCell       if model.is_a?(Hit)
-    EverGreenCell if model.is_a?(Evergreen)
+    PostCell       if model.is_a?(Post)
+    CommentCell    if model.is_a?(Comment)
   end
-
-  def show
-    # ..
-end
 ```
 
-The `#cell` helpers takes care of instantiating the right cell class for you.
+The `#cell` helper takes care of instantiating the right cell class for you.
 
 ```ruby
-cell(:song, Hit.find(1)) #=> creates a HitCell.
+cell(:comment, Post.find(1)) #=> creates a PostCell.
 ```
 
 This also works with collections.
 
 ```ruby
-cell(:song, collection: [@hit, @song]) #=> renders HitCell, then SongCell.
-```
-
-Multiple calls to `::builds` will be ORed. If no block returns a class, the original class will be used (`SongCell`). Builders are inherited.
-
-
-## View Inheritance
-
-
-
-## Asset Pipeline
-
-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.
-
-    ```ruby
-    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.
-
-    ```javascript
-    //=# require comments
-    ```
-
-    Same goes into `app/assets/application.css.sass`.
-
-    ```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.
-
-## View Inheritance
-
-This is where OOP comes back to your view.
-
-* __Inherit code__ into your cells by deriving more abstract cells.
-* __Inherit views__ from parent cells.
-
-
-### Sharing Views
-
-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.
-
-```ruby
-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`.
-
-```ruby
-class Comment::FormCell < Cell::Rails
-  inherit_views CommentCell
-```
-
-When rendering views in `FormCell`, the view directories to look for templates will be inherited.
-
-
-
-
-
-### Call
-
-The `#call` method also accepts a block and yields `self` (the cell instance) to it. This is extremely helpful for using `content_for` outside of the cell.
-
-```ruby
-  = cell(:song, Song.last).call(:show) do |cell|
-    content_for :footer, cell.footer
+cell(:comment, collection: [@post, @comment]) #=> renders PostCell, then CommentCell.
 ```
 
-Note how the block is run in the global view's context, allowing you to use global helpers like `content_for`.
-
-
-## Using Decorators (Twins)
-
-You need to include the `disposable` gem in order to use this.
-
-````ruby
-gem "disposable"
-```
-
-With Cells 3.12, a new experimental concept enters the stage: Decorators in view models. As the view model should only contain logic related to presentation (which can get quite a bit), decorators - called _Twins_ -  can be defined and automatically setup for your model.
-
-Twins are a general concept in Trailblazer and are used everywhere where representers, forms, operations or cells need additional logic that has to be shared between layers. So, this extra step allows re-using your decorator for presentations other than the cell, e.g. in a JSON API, tests, etc.
-
-Also, logic that simply doesn't belong to in a view-related class goes into a twin. That could be code to figure out if a user in logged in.
-
-```ruby
-class SongCell < Cell::ViewModel
-  include Properties
-
-  class Twin < Cell::Twin # this is your decorator
-    property :title
-    property :id
-    option :in_stock?
-  end
+Multiple calls to `::builds` will be ORed. If no block returns a class, the original class will be used (`CommentCell`). Builders are inherited.
 
-  properties Twin
 
-  def show
-    if in_stock?
-      "You're lucky #{title} (#{id}) is in stock!"
-    end
-  end
-end
-```
-
-In this example, we define the twin _in_ the cell itself. That could be done anywhere, as long as you tell the cell where to find the twin (`properties Twin`).
-
-### Creating A Twin Cell
+## Caching
 
-You create your cell as follows.
+For every cell class you can define caching per state. Without any configuration the cell will run and render the state once. In following invocations, the cached fragment is returned.
 
 ```ruby
-cell("song", Song.find(1), in_stock?: true)
-```
-
-Internally, a twin is created from the arguments and passed to the view model. The view model cell now only works on the twin, not on the model anymore.
-
-The twin simply acts as a delegator between the cell and the model: attributes defined with `property` are copied from the model, `option` values _have_ to be passed explicitely to the constructor. The twin defines an _interface_ for using your cell.
-
-Another awesome thing is that you can now easily test your cell by "mocking" values.
+class CommentCell < Cell::ViewModel
+  cache :show
 
-```ruby
-it "renders nicely" do
-  cell("song", song, in_stock?: true, title: "Mocked Song Title").must_match ...
+  # ..
 end
 ```
 
-The twin will simply use the passed `:title` and not copy the title from the song model, making it really easy to test edge cases in your view model.
-
-### Extending Decorators
-
-A decorator without any logic only gives you a tiny improvement, they become really helpful when including your own decorator logic.
+The `::cache` method will forward options to the caching engine.
 
 ```ruby
-class Twin < Cell::Twin # this is your decorator
-  property :title
-  property :id
-  option :in_stock?
-
-  def title
-    super.downcase # super to retrieve the original title from model!
-  end
-end
+cache :show, expires_in: 10.minutes
 ```
 
-The same logic can now be used in a cell, a JSON or XML API endpoint or in the model layer.
-
-Note: If there's enough interest, this could also be extended to work with draper and other decoration gems.
-
-### Nested Rendering
-
-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.
+You can also compute your own cache key, use dynamic keys, cache tags, and so on.
 
 ```ruby
-class SongCell < Cell::ViewModel
-  include TimeagoHelper
-
-  property :title
-
-  # ...
-
-  def author_box
-    render :author # same as render view: :author
-  end
-end
+cache :show { |model, options| "comment/#{model.id}/#{model.updated_at}" }
+cache :show, :if => lambda { |*| has_changed? }
+cache :show, :tags: lambda { |model, options| "comment-#{model.id}" }
 ```
 
-This will simply render the `author.haml` template in the same context as the `show` view, meaning you might use helpers, again.
-
-
-
-### Cells in ActionMailer
-
-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](https://github.com/weppos/actionmailer_with_request) which (suprise!) brings request object to the ActionMailer.
-
-
+Caching is documented [here](http://trailblazerb.org/gems/cells/caching.html) and in chapter 8 of the [Trailblazer book](http://leanpub.com/trailblazer).
 
-## Cells is Rails::Engine aware!
 
-Now `Rails::Engine`s 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.
+## The Book
 
+Cells is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy my book](https://leanpub.com/trailblazer) to support the development and to learn all the cool stuff about Cells. The book discusses the following.
 
-## Generator Options
+<a href="https://leanpub.com/trailblazer">
+![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
+</a>
 
-By default, generated cells inherit from `Cell::ViewModel`. If you want to change this, specify your new class name in `config/application.rb`:
+* Basic view models, replacing helpers, and how to structure your view into cell components (chapter 2 and 4).
+* Advanced Cells API (chapter 4 and 6).
+* Testing Cells (chapter 4 and 6).
+* Cells Pagination with AJAX (chapter 6).
+* View Caching and Expiring (chapter 8).
 
-### Base Class
+More chapters are coming.
 
-```ruby
-module MyApp
-  class Application < Rails::Application
-    config.generators do |g|
-      g.base_cell_class "ApplicationCell"
-    end
-  end
-end
-```
+The book picks up where the README leaves off. Go grab a copy and support us - it talks about object- and view design and covers all aspects of the API.
 
 
 ## Undocumented Features