cells 3.11.3 → 4.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1733d66b3c4c59a504f758006fbc1a4391b04827
-  data.tar.gz: 2ba5c6cfba87ec5f9df760f15e2f40fc5a4db44d
+  metadata.gz: 26d77a00fc2075f5869dedf7b99b55afc2df0eec
+  data.tar.gz: 139402563ae105fc1c501f2a848a7b7f0491452d
 SHA512:
-  metadata.gz: 66b45a320031b1d401a8a4714f4e31f6944d17302118b3343810f0533c4d588a76f08428d295bbd8811048d36c3a66817e915a958831c8f580d476c82225f689
-  data.tar.gz: c18f7d86f22a3d2e4fb5ac0671c0a1aa92ae467dfaaea2fbb9c7e0c8e5888fa20ffcf6673a27b93a95b67dd2d89f59c8ff4e880c4e0f575fa1279e0c257e753f
+  metadata.gz: 5b5d3fae08a561a5b24d976e137d8e91d9172487318d4621d281295cd45eecd61ac81820aa27c64afc3a9385e891354efbc1c8c371daeb14b0dabf9d3c121f9d
+  data.tar.gz: c933f9a2a9e4fc9850ad5257e725e5070a2b248070dfa0bd012d095016b6866adea340a85910b09fe65c1352911d838c29e63e92c5e4ee1525f90fb9ef7bcd95

data/.gitignore

@@ -3,7 +3,7 @@ pkg
 *.gem
 .*~
 .bundle
-Gemfile*.lock
+*.lock
 test/dummy/log/
 test/dummy/tmp/
 /.rvmrc

data/.travis.yml

@@ -1,19 +1,21 @@
+language: ruby
 rvm:
-  - 1.9.3
+#  - 2.2
+  - 2.1
   - 2.0.0
+  - 1.9.3
   - jruby-19mode
+
+sudo: false
+
+bundler_args: '--without local_development --jobs 3 --retry 3'
+
+script: bundle exec rake
+
 notifications:
   irc: "irc.freenode.org#cells"
 gemfile:
-  - gemfiles/Gemfile.rails3-0
-  - gemfiles/Gemfile.rails3-1
-  - gemfiles/Gemfile.rails3-2
-  - gemfiles/Gemfile.rails4-0
-  - gemfiles/Gemfile.rails4-1
-
-matrix:
-  exclude:
-    - rvm: 2.0.0
-      gemfile: gemfiles/Gemfile.rails3-0
-    - rvm: 2.0.0
-      gemfile: gemfiles/Gemfile.rails3-1
+  - gemfiles/rails4.2.gemfile
+  - gemfiles/rails4.1.gemfile
+  - gemfiles/rails4.0.gemfile
+  - gemfiles/rails3.2.gemfile

data/Appraisals

@@ -0,0 +1,23 @@
+appraise 'rails3.2' do
+    gem 'railties', github: 'rails/rails', branch: '3-2-stable'
+    gem 'tzinfo'
+    gem 'minitest', '4.7.5'
+end
+
+appraise "rails4.0" do
+    gem 'railties', github: 'rails/rails', branch: '4-0-stable'
+    gem 'activemodel', github: 'rails/rails', branch: '4-0-stable'
+    gem 'minitest', '4.7.5'
+end
+
+appraise "rails4.1" do
+    gem 'railties', github: 'rails/rails', branch: '4-1-stable'
+    gem 'activemodel', github: 'rails/rails', branch: '4-1-stable'
+    gem 'minitest', '~> 5.2'
+end
+
+appraise "rails4.2" do
+    gem 'railties', github: 'rails/rails', branch: '4-2-stable'
+    gem 'activemodel', github: 'rails/rails', branch: '4-2-stable'
+    gem 'minitest', '~> 5.2'
+end

data/CHANGES.md

@@ -1,6 +1,23 @@
-## 3.11.3
+## 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.
+* **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.
+* **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.
+* Builders are now defined using `::builds`, not `::build`.
+
+### Removed
+
+* `Cell::Rails` and `Cell::Base` got removed. Every cell is `ViewModel` or `Concept` now.
+
+### 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.
 
-* Make Cells work with Rails 4.2. Thanks to @pwim and @did!
 
 ## 3.11.2
 
@@ -36,8 +53,8 @@
 * Concept cells look for layouts in their self-contained views directory.
 * Add generator for Concept cells: `rails g concept Comment`
 
-## 3.10.1
 
+## 3.10.1
 Allow packaging assets for Rails' asset pipeline into cells. This is still experimental but works great. I love it.
 
 ## 3.10.0

data/Gemfile

@@ -2,11 +2,9 @@ source 'https://rubygems.org'
 
 gemspec
 
-#gem "rails" , :path => "../rayls"
+gem 'minitest-reporters'
+gem 'pry-byebug'  , platforms: [:mri_20, :mri_21]
+gem 'appraisal'
+gem 'rake'
+gem 'test_xml'
 
-gem "rails", "~> 3.2.12"
-gem 'minitest', '4.7.5'
-
-# gem 'uber', :path => "../uber"
-
-gem 'disposable', path: '../disposable'

data/README.md

@@ -5,28 +5,57 @@
 
 ## Overview
 
-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.
+Cells allow you to encapsulate parts of your page into separate MVC components. These components are called _view models_.
 
-While they improve your overall software architecture by abstracting logic into an encapsulated OOP instance, cells also maximise reuseability within or across projects.
+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`.
 
-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`.
+As you have already noticed we use _cell_ and _view model_ interchangeably here.
 
 
-## View Models
+## The Book
 
-Since version 3.9 cells comes with two "dialects": You can still use a cell like a controller. However, the new [view model](https://github.com/apotonick/cells#view-models-explained) "dialect" supercedes the traditional cell. It allows you to treat a cell more object-oriented while providing an alternative approach to helpers.
+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.
 
-While the old dialect still works, we strongly recommend using a cell as a view model.
+<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 3).
+* Advanced Cells API (chapter 3 and 6).
+* Testing Cells (chapter 3 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
 
-Cells run with all Rails >= 3.0. For 2.3 support [see below](#rails-23-note).
+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.
+
+```ruby
+gem 'cells', "~> 4.0.0"
+```
+
+## 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).
 
 ```ruby
-gem 'cells'
+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.
+
+
 ## File Layout
 
 Cells are placed in `app/cells`.
@@ -43,91 +72,306 @@ app
 
 ## Generate
 
-Creating a cell is nothing more than
+Use the bundled generator to set up a cell.
 
 ```shell
-rails generate cell cart show -e haml
+rails generate cell comment
 ```
 
 ```
 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
+create  app/cells/comment
+create  app/cells/comment_cell.rb
+create  app/cells/comment/show.erb
 ```
 
-That looks very familiar.
 
-## Render the cell
+## Rendering View Models
 
-Now, render your cart. Why not put it in `layouts/application.html.erb` for now?
+Suppose we are to render a "partial" for `Comment` model
 
-```erb
-<div id="header">
-  <%= render_cell :cart, :show, :user => @current_user %>
+```ruby
+@comment = Comment.find(1)
 ```
 
-Feels like rendering a controller action. For good encapsulation we pass the current `user` from outside into the cell - a dependency injection.
+Cells brings you one helper method `#cell` to be used in your controller views or layouts.
 
-## Code
+```haml
+= cell(:comment, @comment)
+```
 
-Time to improve our cell code. Let's start with `app/cells/cart_cell.rb`:
+This is the short form of rendering a cell. Simple, isn't it?
 
-```ruby
-class CartCell < Cell::Rails
-  def show(args)
-    user    = args[:user]
-    @items  = user.items_in_cart
+Note that a view model _always_ requires a model in the constructor (or a composition). This doesn't have to be an `ActiveRecord` object but can be any type of Ruby object you want to present.
 
-    render  # renders show.html.haml
+To understand invoking cells, here's the long form of it.
+
+```haml
+= cell(:comment, @comment).call(:show)
+```
+
+1. `#cell(..)` simply returns the cell instance. You can do whatever you want with it.
+2. `.call(:show)` will invoke the `#show` method respecting caching settings.
+
+When rendering cells in views, you can skip the `call` part as this is implicitely done by the template.
+
+Please [refer to the docs](#invocation-styles) for different ways of invoking view models.
+
+
+## View Model Classes
+
+A view model is always implemented as a class. This gives you encapsulation, proper inheritance and namespacing out-of-the-box.
+
+```ruby
+class CommentCell < Cell::ViewModel
+  def show
+    render
   end
 end
 ```
 
-Is that a controller? Hell, yeah. We even got a `#render` method as we know it from the good ol' `ActionController`.
+Calling `#render` will render the cell's `show.haml` template, located in `app/cells/comment`. Invoking `render` is explicit: this means, it really returns the rendered view string, allowing you to modify the HTML afterwards.
+
+```ruby
+def show
+  "<div>" + render + "</div>"
+end
+```
+
+## Views In Theory
+
+In Cells, we don't distinguish between _view_ or _partial_. Every view you render is a partial, every partial a view. You can render views inside views, compose complex UI blocks with multiple templates and go crazy. This is what cells _views_ are made for.
+
+Cells supports all template engines that are supported by the excellent [tilt](https://github.com/rtomayko/tilt) gem - namely, this is ERB, HAML, Slim, and many more.
+
+In these examples, we're using HAML.
+
+BTW, Cells doesn't include the format into the view name. 99% of all cells render HTML anyway, so we prefer short names like `show.haml`.
 
 
-## Views
+## Views In Practice
 
-Since a plain call to `#render` will start rendering `app/cells/cart/show.html.haml` we should put some meaningful markup there.
+Let's check out the `show.haml` view to see how they work.
 
 ```haml
-#cart
-  You have #{@items.size} items in your shopping cart.
+-# app/cells/comment/show.haml
+
+%h1 Comment
+
+= model.body
+By
+= link_to model.author.name, model.author
 ```
 
-### ERB? Haml? Builder?
+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
 
-Yes, Cells support all template types that are supported by Rails itself. Remember- it's a controller!
+This is how a typical view looks in a view model.
 
-### Helpers
+```haml
+-# app/cells/comment/show.haml
+
+%h1 Comment
 
-Yes, Cells have helpers just like controllers. If you need some specific helper, do
+= body
+By
+= author_link
+```
+
+The methods we call in the view now need to be defined in the cell instance.
 
 ```ruby
-class CartCell < Cell::Rails
-  helper MyExtraHelper
+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
+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.
+
+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
+
+Often, as in the `#body` method, you simply need to delegate properties from the model. This can be done automatically using `::property`.
+
+```ruby
+class CommentCell < Cell::ViewModel
+  def show
+    render
+  end
+
+private
+  property :body
+  property :author
+
+  def author_link
+    link_to author.name, author
+  end
+end
+```
+
+Readers are automatically created when defined with `::property`.
+
+
+## Render
+
+multiple times allowed
+:view
+:format ".html"
+template_engine
+view_paths
+
+
+## Invocation styles
+
+The explicit, long form allows you rendering cells in views, in controllers, mailers, etc.
+
+```ruby
+cell(:comment, @comment).call(:show)
 ```
 
-and it will be around in your cart views.
+As `:show` is the default action, you don't have to specify it.
 
-### Partials?
+```ruby
+cell(:comment, @comment).call
+```
 
-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`.
+In views, the template engine will automatically call `cell.to_s`. It does that for every object passed in as a placeholder. `ViewModel#to_s` exists and is aliased to `#call`, which allows to omit that part in a view.
 
 ```haml
-/ app/cells/comment/show.haml
+= cell(:comment, @comment)
+```
 
-%h1 All comments
+If you want, you can also call public methods directly on your cell. Note that this does _not_ respect caching, though.
 
-%p
-  = render :view => 'items'
+```haml
+= cell(:comment, @comment).avatar
 ```
 
-## File Structure
+## Passing Options
+
+There's several ways to inject additional state into your cell.
+
+### Object Style
+
+Cells can receive any set of options you need. Usually, a hash containing additional options is passed as the last argument.
+
+```ruby
+cell(:comment, @comment, layout: :fancy)
+```
+
+The third argument is accessable via `#options` in the instance.
+
+```ruby
+def show
+  render layout: options[:layout]
+end
+```
+
+### Functional Style
+
+You can also pass options to the action method itself, making your cell a bit more functional with less state.
+
+```ruby
+cell(:comment, @comment).call(:show, layout: :fancy)
+```
+
+Make sure the method is ready to process those arguments.
+
+```ruby
+def show(layout=:default)
+  render layout: layout
+end
+```
+
+## Collections
+
+You can render a collection of models where each item is rendered using a cell.
+
+```ruby
+= cell(:song, collection: Song.all)
+```
+
+Note that there is no `.call` needed. This is identical to the following snippet.
+
+```ruby
+- Song.all.each do |song|
+  = cell(:song, song).call(:show)
+```
+
+Options are passed to every cell.
+
+```ruby
+= cell(:song, collection: Song.all, genre: "Heavy Metal", user: current_user)
+```
+
+The collection invocation per default calls `#show`. Use `:method` if you need another method to be called.
+
+```ruby
+= cell(:song, collection: Song.all, method: :detail)
+```
+
+## Builder
+
+Often, it is good practice to replace decider code from views or classes into separate sub-cells. Or in case you want to render a polymorphic collection, builders come in handy.
+
+Builders allow instantiating different cell classes for different models and options.
+
+```ruby
+class SongCell < Cell::ViewModel
+  builds do |model, options|
+    HitCell       if model.is_a?(Hit)
+    EverGreenCell if model.is_a?(Evergreen)
+  end
+
+  def show
+    # ..
+end
+```
+
+The `#cell` helpers takes care of instantiating the right cell class for you.
+
+```ruby
+cell(:song, Hit.find(1)) #=> creates a HitCell.
+```
+
+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
+
 
-TODO: rails g concept Song => show.haml,
+
+# TODO: merge stuff below!
+
+## File Structure
 
 In Cells 3.10 we introduce a new _optional_ file structure integrating with [Trailblazer](https://github.com/apotonick/trailblazer)'s "concept-oriented" layout.
 
@@ -209,22 +453,6 @@ Adding the assets files to the asset pipeline currently involves two steps (I kn
 
 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.
 
-### Rendering Global Partials
-
-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.
-
-```ruby
-class MapCell < Cell::Rails
-  append_view_path "app/views"
-
-  def show
-    render partial: 'shared/map_form'
-  end
-```
-
-Note that you have to use `render partial:` which will then look in the global view directory and render the partial found at `app/views/shared/map_form.html.haml`.
-
-
 ## View Inheritance
 
 This is where OOP comes back to your view.
@@ -252,25 +480,6 @@ class Comment::FormCell < Cell::Rails
 
 When rendering views in `FormCell`, the view directories to look for templates will be inherited.
 
-### Builders
-
-Let `render_cell` take care of creating the right cell. Just configure your super-cell properly.
-
-```ruby
-class LoginCell < Cell::Rails
-  build do
-    UnauthorizedUserCell unless logged_in?
-  end
-```
-
-A call to
-
-```ruby
-render_cell(:login, :box)
-```
-
-will render the configured `UnauthorizedUserCell` instead of the original `LoginCell` if the login test fails.
-
 
 ## Caching
 
@@ -423,100 +632,6 @@ To run your specs we got a rake task, too!
 rake spec:cells
 ```
 
-# View Models, Explained
-
-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.
-
-
-```ruby
-# app/cells/song_cell.rb
-class SongCell < Cell::ViewModel
-end
-```
-
-### Creation
-
-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.
-
-```ruby
-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.
-
-### Rendering
-
-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.
-
-```ruby
-class SongCell < Cell::ViewModel
-  def show
-    render
-  end
-end
-```
-
-The `render` call will render the cell's `show` view.
-
-### Views
-
-```haml
-- # 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.
-
-### Helpers
-
-```ruby
-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.
-
-### Properties
-
-Often, it is helpful to automatically expose some reader methods to the model. You can do that with `::property`.
-
-```ruby
-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`.
 
 ### Call
 
@@ -677,48 +792,7 @@ ActionMailer doesn't have request object, so if you inherit from Cell::Rails you
 
 You can fix that with [actionmailer_with_request](https://github.com/weppos/actionmailer_with_request) which (suprise!) brings request object to the ActionMailer.
 
-## Using Rails Gems Like simple_form Outside Of Rails
-
-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](https://github.com/plataformatec/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.
-
-```ruby
-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).
-
-```ruby
-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.
-
-```erb
-<%= 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.
 
 ## Cells is Rails::Engine aware!
 
@@ -727,7 +801,7 @@ Now `Rails::Engine`s can contribute to Cells view paths. By default, any 'app/ce
 
 ## Generator Options
 
-By default, generated cells inherit from `Cell::Rails`. If you want to change this, specify your new class name in `config/application.rb`:
+By default, generated cells inherit from `Cell::ViewModel`. If you want to change this, specify your new class name in `config/application.rb`:
 
 ### Base Class
 
@@ -751,33 +825,40 @@ config.generators do |g|
 end
 ```
 
-## Rails 2.3 note
 
-### Installation
+## Capture Support
 
-```shell
-gem install cells -v 3.3.9
-```
+If you need a global `#content_for` use the [cells-capture](https://github.com/apotonick/cells-capture) gem.
 
-In order to copy the cells rake tasks to your app, run
 
-```shell
-script/generate cells_install
-```
+## Undocumented Features
 
-## Capture Support
+*(Please don't read this section!)*
 
-If you need a global `#content_for` use the [cells-capture](https://github.com/apotonick/cells-capture) gem.
+### Rendering Global Partials
 
-## More features
+Although not recommended, you can also render global partials from a cell. Be warned, though, that they will be rendered using our stack, and you might have to include helpers into your view model.
 
-Cells can do more.
+This works by including `Partial` and the corresponding `:partial` option.
 
-* __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.
+```ruby
+class Cell < Cell::ViewModel
+  include Partial
 
-Go for it, you'll love it!
+  def show
+    render partial: "../views/shared/map.html" # app/views/shared/map.html.haml
+  end
+```
+
+The provided path is relative to your cell's `::view_paths` directory. The format has to be added to the file name, the template engine suffix will be used from the cell.
+
+You can provide the format in the `render` call, too.
+
+```ruby
+render partial: "../views/shared/map", formats: [:html]
+```
 
+This was mainly added to provide compatibility with 3rd-party gems like [Kaminari and Cells](https://github.com/apotonick/kaminari-cells) that rely on rendering partials within a cell.
 
 ## LICENSE