cells 3.10.1 → 3.11.0

data/.travis.yml

@@ -10,3 +10,10 @@ gemfile:
   - 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

data/CHANGES.md

@@ -1,3 +1,21 @@
+## 3.11.0
+
+* Deprecated `Cell::Rails::ViewModel`, please inherit: `class SongCell < Cell::ViewModel`.
+* `ViewModel#call` is now the prefered way to invoke the rendering flow. Without any argument, `call` will run `render_state(:show)`. Pass in any method name you want.
+* Added `Caching::Notifications`.
+* Added `cell(:song, collection: [song1, song2])` to render collections. This only works with ViewModel (and, of course, Concept, too).
+* Added `::inherit_views` to only inherit views whereas real class inheritance would inherit all the dark past of the class.
+* `::build_for` removed/privatized/changed. Use `Cell::Base::cell_for` instead.
+* `Base::_parent_prefixes` is no longer used, if you override that somewhere in your cells it will break. We have our own implementation for computing the controller's prefixes in `Cell::Base::Prefixes` (simpler).
+* `#expire_cell_state` doesn't take symbols anymore, only the real cell class name.
+* Remove `Cell::Base.setup_view_paths!` and `Cell::Base::DEFAULT_VIEW_PATHS` and the associated Railtie. I don't know why this code survived 3 major versions, if you wanna set you own view paths just use `Cell::Base.view_paths=`.
+* Add `Base::self_contained!`.
+* Add `Base::inherit_views`.
+
+### Concept
+* `#concept` helper is mixed into all views as an alternative to `#cell` and `#render_cell`. Let us know if we should do that conditionally, only.
+* Concept cells look for layouts in their self-contained views directory.
+
 ## 3.10.1
 
 Allow packaging assets for Rails' asset pipeline into cells. This is still experimental but works great. I love it.

data/Gemfile

@@ -5,4 +5,4 @@ gemspec
 #gem "rails" , :path => "../rayls"
 
 gem "rails", "~> 3.2.12"
-gem 'minitest', '4.7.5'
+gem 'minitest', '4.7.5'

data/README.md

@@ -1,35 +1,43 @@
 # Cells
 
-**View Components for Rails.**
+*View Components for Rails.*
+
 
 ## Overview
 
-Say you're writing a Rails online shop - the shopping cart is reappearing again and again in every view. You're thinking about a clean solution for that part. A mixture of controller code, before-filters, partials and helpers?
+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.
 
-No. That sucks. Take Cells.
+While they improve your overall software architecture by abstracting logic into an encapsulated OOP instance, cells also maximise reuseability within or across projects.
 
-Cells are View Components for Rails. They look and feel like controllers. They don't have no `DoubleRenderError`. They can be rendered everywhere in your controllers or views. They are cacheable, testable, fast and wonderful. They bring back OOP to your view and improve your software design.
+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`.
 
-And the best: You can have as many cells in your page as you need!
 
+## View Models
 
-Note: 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) "dialect" allows you to treat a cell more object-oriented while providing an alternative approach to helpers.
+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" allows you to treat a cell more object-oriented while providing an alternative approach to helpers.
 
-## Installation
+While the old dialect still works, we strongly recommend using a cell as a view model.
 
-It's a gem!
 
-Rails >= 3.0:
+## Installation
 
-```shell
-gem install cells
+```ruby
+gem 'cells'
 ```
 
-Rails 2.3:
+## File Layout
+
+Cells are placed in `app/cells`.
 
-```shell
-gem install cells -v 3.3.9
 ```
+app
+├── cells
+│   ├── comment_cell.rb
+│   ├── comment
+│   │   ├── show.haml
+│   │   ├── list.haml
+```
+
 
 ## Generate
 
@@ -104,18 +112,22 @@ and it will be around in your cart views.
 
 ### Partials?
 
-Yeah, we do support rendering partials in views. Nevertheless, we discourage _partials_ at all.
-
-The distinction between partials and views is making things more complex, so why should we have two kinds of view types? Use ordinary views instead, they're fine.
+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`.
 
 ```haml
+/ app/cells/comment/show.haml
+
+%h1 All comments
+
 %p
   = render :view => 'items'
 ```
 
 ## 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.
+TODO: rails g concept Song => show.haml,
+
+In Cells 3.10 we introduce a new _optional_ file structure integrating with [Trailblazer](https://github.com/apotonick/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.
 
@@ -213,6 +225,25 @@ This is where OOP comes back to your view.
 * __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.
+
 ### Builders
 
 Let `render_cell` take care of creating the right cell. Just configure your super-cell properly.
@@ -291,12 +322,37 @@ You can expand the state's cache key by appending a versioner block to the `::ca
 ```ruby
 class CartCell < Cell::Rails
   cache :show do |options|
-    options[:items].md5
+    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.
+
+```ruby
+class CartCell < Cell::Rails
+  cache :show do |options|
+    [id, options[:items].md5]
   end
 ```
 
-The block's return value is appended to the state key: `"cells/cart/show/0ecb1360644ce665a4ef"`.
+Resulting in: `"cells/cart/show/1/0ecb1360644ce665a4ef"`.
+
+
+### Debugging Cache
 
+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.
+
+```ruby
+class Comment::Cell < Cell::Rails
+  include Cell::Caching::Notifications
+```
 
 ### Inheritance
 
@@ -359,81 +415,144 @@ To run your specs we got a rake task, too!
 rake spec:cells
 ```
 
-# View Models
+# View Models, Explained
 
-Cells 3.9 brings a new dialect to cells: view models.
+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.
 
-Think of a view model as a cell decorating a model or a collection. In this mode, helpers are nothing more than instance methods of your cell class, making helpers predictable and scoped.
 
 ```ruby
-class SongCell < Cell::Rails
-  include ViewModel
+# app/cells/song_cell.rb
+class SongCell < Cell::ViewModel
+end
+```
 
-  property :title
+### 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
-
-  def self_link
-    link_to(title, song_url(model))
-  end
 end
 ```
 
-### Creation
+The `render` call will render the cell's `show` view.
+
+### Views
 
-Creating the view model should usually happen in the controller.
+```haml
+- # app/cells/song/show.haml
+
+%h1 #{title}
+
+%p Written at #{composed_at}
+
+= author_box
+```
+
+We strongly recommend to invoke methods, only, 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 DashboardController < ApplicationController
+class SongCell < Cell::ViewModel
+  include TimeagoHelper
 
-  def index
-    @song = Song.find(1)
+  def show
+    render
+  end
 
-    @cell = cell(:song, @song)
+  def composed_at
+    timeago(model.created_at)
   end
+end
 ```
 
-You can now grab an instance of your cell using the `#cell` method. The 2nd argument will be the cell's decorated model.
+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.
 
-Have a look at how to use this cell in your controller view.
+The `#model` methods lets you access the wrapped `Song` instance we passed into the cell when creating it.
 
-```haml
-= @cell.show # renders its show view.
-```
+### Properties
 
-You no longer use the `#render_cell` helper but call any method on that cell. Usually, this is a state (or "action") like `show`.
+Often, it is helpful to automatically expose some reader methods to the model. You can do that with `::property`.
 
-### Helpers
+```ruby
+class SongCell < Cell::ViewModel
+  include TimeagoHelper
 
-Note that this doesn't have to be a rendering state, it could be any instance method (aka "helper").
+  property :title
 
-```haml
-= @cell.self_link
+  # ...
+end
 ```
 
-As all helpers are now instance methods, the `#self_link` example can use any existing helper (as the URL helpers) on the instance level.
+You can now safely use `#title` in the view (and, in the cell class), it is delegated to `model.title`.
+
+### Nested Rendering
 
-Attributes declared using ``::property` are automatically delegated to the decorated model.
+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.
 
 ```ruby
-@cell.title # delegated to @song.title
+class SongCell < Cell::ViewModel
+  include TimeagoHelper
+
+  property :title
+
+  # ...
+
+  def author_box
+    render :author # same as render view: :author
+  end
+end
 ```
 
-### Views
+This will simply render the `author.haml` template in the same context as the `show` view, meaning you might use helpers, again.
 
-This greatly reduces wiring in the cell view (which is still in `app/cells/song/show.haml`).
+### Encapsulation
 
-```haml
-%h1
-  = title
+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](http://nicksda.apotomo.de).
 
-Bookmark! #{self_link}
+### Alternative Instantiation
+
+You don't need to pass in a model, it can also be a hash for a composition.
+
+```ruby
+  cell(album, song: song, composer: album.composer)
 ```
 
-Making the cell instance itself the view context should be an interesting alternative for many views.
+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:
+
+```ruby
+  property :title, on: :song
+  property :last_name, on: :composer
+```
 
 
 ## Mountable Cells
@@ -536,6 +655,12 @@ end
 
 ## Rails 2.3 note
 
+### Installation
+
+```shell
+gem install cells -v 3.3.9
+```
+
 In order to copy the cells rake tasks to your app, run
 
 ```shell
@@ -558,7 +683,7 @@ Go for it, you'll love it!
 
 ## LICENSE
 
-Copyright (c) 2007-2013, Nick Sutterer
+Copyright (c) 2007-2014, Nick Sutterer
 
 Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
 

data/TODO.md

@@ -0,0 +1,9 @@
+# 4.0
+
+* Get rid of the annoying `ActionController` dependency that needs to be passed into each cell. We only need it for "contextual links", when people wanna link to the same page. Make them pass in a URL generator object as a normal argument instead.
+* Generated cells will be view models per default.
+* Introduce Composition as in Reform, Representable, etc, when passing in a hash.
+    ```ruby
+      include Composition
+      property :id, on: :comment
+    ```

data/cells.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency "actionpack",  ">= 3.0"
   s.add_dependency "railties",    ">= 3.0"
-  s.add_dependency "uber",        "~> 0.0.4"
+  s.add_dependency "uber",        "~> 0.0.6"
 
   s.add_development_dependency "rake"
   s.add_development_dependency "haml"
@@ -29,4 +29,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency "tzinfo" # FIXME: why the hell do we need this for 3.1?
   s.add_development_dependency "minitest",	">= 4.7.5"
   s.add_development_dependency "activemodel"
+  s.add_development_dependency "capybara"
+  s.add_development_dependency "sprockets"
 end

data/gemfiles/Gemfile.rails4-0

@@ -6,6 +6,7 @@ gemspec path: '../'
 gem 'railties', '4.0.2'
 gem 'activemodel', '4.0.2'
 gem 'minitest', '4.7.5'
-gem 'simple_form', '~> 3.0.0'
+gem 'sprockets', '~> 2.1'
+gem 'sprockets-rails', '~> 2.1.3', :require => 'sprockets/railtie'
 
 gem 'label', :path => "../test/dummy/label"

data/gemfiles/Gemfile.rails4-1

@@ -3,8 +3,10 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in cells.gemspec
 gemspec path: '../'
 
-gem 'railties', '4.1.0.rc2'
-gem 'activemodel', '4.1.0.rc2'
+gem 'railties', '4.1.1'
+gem 'activemodel', '4.1.1'
 gem 'minitest', '5.2.0'
+gem 'sprockets', '~> 2.1'
+gem 'sprockets-rails', '~> 2.1.3', :require => 'sprockets/railtie'
 
-gem 'label', :path => "../test/dummy/label"
+gem 'label', :path => "../test/dummy/label", :require => 'label'

data/lib/cell/base.rb

@@ -5,109 +5,78 @@ require 'cell/rendering'
 require 'cell/dsl'
 
 module Cell
-  module RailsVersion
-    def rails3_0?
-      ::ActionPack::VERSION::MAJOR == 3 and ::ActionPack::VERSION::MINOR == 0
-    end
-
-    def rails3_1_or_more?
-      (::ActionPack::VERSION::MAJOR == 3 and ::ActionPack::VERSION::MINOR >= 1)
-    end
-
-    def rails3_2_or_more?
-      (::ActionPack::VERSION::MAJOR == 3 and ::ActionPack::VERSION::MINOR >= 2)
-    end
-
-    def rails4_0?
-      ::ActionPack::VERSION::MAJOR == 4 and ::ActionPack::VERSION::MINOR == 0
-    end
-
-    def rails4_1_or_more?
-      (::ActionPack::VERSION::MAJOR == 4 and ::ActionPack::VERSION::MINOR >= 1) or ::ActionPack::VERSION::MAJOR > 4
-    end
-    alias_method :rails4_1?, :rails4_1_or_more?
+  require 'uber/version'
+  def self.rails_version
+    Uber::Version.new(::ActionPack::VERSION::STRING)
   end
-  extend RailsVersion # TODO: deprecate in 3.10.
 
 
   class Base < AbstractController::Base
     # TODO: deprecate Base in favour of Cell.
-
     abstract!
-    DEFAULT_VIEW_PATHS = [File.join('app', 'cells')]
 
-    extend Builder
     include AbstractController
     include AbstractController::Rendering, Helpers, Callbacks, Translation, Logger
 
-    require 'cell/rails3_0_strategy' if Cell.rails3_0?
-    require 'cell/rails3_1_strategy' if Cell.rails3_1_or_more?
-    require 'cell/rails4_0_strategy' if Cell.rails4_0?
-    require 'cell/rails4_1_strategy' if Cell.rails4_1_or_more?
+    self.view_paths = "app/cells"
+
+
+    require 'cell/rails3_0_strategy' if Cell.rails_version.~  "3.0"
+    require 'cell/rails3_1_strategy' if Cell.rails_version.~( "3.1", "3.2")
+    require 'cell/rails4_0_strategy' if Cell.rails_version.~  "4.0"
+    require 'cell/rails4_1_strategy' if Cell.rails_version >= "4.1"
     include VersionStrategy
     include Layouts
     include Rendering
     include Caching
     include Cell::DSL
 
+    extend Builder::ClassMethods # ::build DSL method and ::builders.
+
+
     def initialize(*args)
       super() # AbC::Base.
       process_args(*args)
     end
 
-  private
-    def process_args(*)
+    def self.class_from_cell_name(name)
+      "#{name}_cell".classify.constantize
     end
 
-    class View < ActionView::Base
-      def self.prepare(modules)
-        # TODO: remove for 4.0 if PR https://github.com/rails/rails/pull/6826 is merged.
-        Class.new(self) do  # DISCUSS: why are we mixing that stuff into this _anonymous_ class at all? that makes things super complicated.
-          include *modules.reverse
-        end
+
+    class << self
+      # Main entry point for instantiating cells.
+      def cell_for(name, *args)
+        Builder.new(class_from_cell_name(name), self).call(*args)
       end
 
-      def render(*args, &block)
-        options = args.first.is_a?(::Hash) ? args.first : {}  # this is copied from #render by intention.
+      alias_method :create_cell_for, :cell_for # TODO: remove us in 3.12.
+      ActiveSupport::Deprecation.deprecate_methods(self, :create_cell_for => :cell_for)
+    end
 
-        return controller.render(*args, &block) if options[:state] or options[:view]
-        super
-      end
+  private
+    def process_args(*)
     end
 
 
-    def self.view_context_class
+    def self.view_context_class # DISCUSS: this is only needed for non-vm cells.
       @view_context_class ||= begin
         Cell::Base::View.prepare(helper_modules)
       end
     end
 
-    # Called in Railtie at initialization time.
-    def self.setup_view_paths!
-      self.view_paths = self::DEFAULT_VIEW_PATHS
-    end
-
     def self.controller_path
       @controller_path ||= name.sub(/Cell$/, '').underscore unless anonymous?
     end
 
 
-    # Enforces the new trailblazer directory layout where cells (or concepts in general) are fully self-contained in its own directory.
-    module SelfContained
-      def self_contained!
-        include Prefixes
-      end
-
-      module Prefixes
-        def _prefixes
-          @_prefixes ||= begin
-            super.tap do |prefixes|
-              prefixes[-1] = "#{controller_path}/views" # replace comment/.
-            end
-          end
-        end
-      end
-    end
+    require 'cell/base/view'
+    require 'cell/base/prefixes'
+    include Prefixes
+    require 'cell/base/self_contained'
     extend SelfContained
   end
+
+  autoload :ViewModel, 'cell/view_model'
+  autoload :Concept,   'cell/concept'
 end