cells 3.8.8 → 3.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5f0e0a0f0e9e01a740baa8dcabe12f82876ca1ef
+  data.tar.gz: a0a66d1ecd8e09265efc3a8c5fe7e293bc8df5d1
+SHA512:
+  metadata.gz: 33577d3b2e94dde50fb8f68ff2695fbaa1dbc73a04fb839fbb14e4ca215f83d01b854ec57454cf75488210a2ef8060312cdfc9ae865ece439af2fd84ab4df111
+  data.tar.gz: 7c03b94c1a6dee95e672a0411025e9fa7afb6414d4a3c43a4038b70e45f381f4bde3d9cf66a2364f953ef381b27220af690da67685f5aaddb8be8e09d4f3a4c0

data/.gitignore

@@ -1,8 +1,9 @@
 .DS_Store
 pkg
+*.gem
 .*~
 .bundle
 Gemfile*.lock
-test/dummy/log/*.log
+test/dummy/log/
 test/dummy/tmp/
 /.rvmrc

data/.travis.yml

@@ -1,8 +1,11 @@
-rvm: 1.9.2
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode
 notifications:
   irc: "irc.freenode.org#cells"
 gemfile:
-  - Gemfile
   - gemfiles/Gemfile.rails3-0
   - gemfiles/Gemfile.rails3-1
   - gemfiles/Gemfile.rails3-2
+  - gemfiles/Gemfile.rails4-0

data/CHANGES.textile

@@ -1,3 +1,11 @@
+h2. 3.9.0
+
+* Cells in engines are now recognized under Rails 4.0.
+* Introducing @#cell@ and @#cell_for@ to instantiate cells in ActionController and ActionView.
+* Adding @Cell::Rails::ViewModel@ as a new "dialect" of working with cells.
+* Add @Cell::Base#process_args@ which is called in the initializer to handle arguments passed into the constructor.
+* Setting @controller in your @Cell::TestCase@ no longer get overridden by us.
+
 h2. 3.8.8
 
 * Maintenance release.
@@ -24,7 +32,7 @@ h2. 3.8.4
 
 h2. 3.8.3
 
-* Added @Engines.existent_directories_for@ to prevent Rails 3.0 from crashing when it detects engines. 
+* Added @Engines.existent_directories_for@ to prevent Rails 3.0 from crashing when it detects engines.
 
 h2. 3.8.2
 
@@ -40,7 +48,7 @@ h2. 3.8.0
 * New API (note that @controller@ isn't the first argument anymore):
 ** @Rails.create_cell_for(name, controller)@
 ** @Rails.render_cell_for(name, state, controller, *args)@
-* Moved builder methods to @Cell::Builder@ module. 
+* Moved builder methods to @Cell::Builder@ module.
 * @DEFAULT_VIEW_PATHS@ is now in @Cell::Base@.
 * Removed the monkey-patch that made state-args work in Rails <= 3.0.3. Upgrade to +3.0.4.
 
@@ -60,18 +68,18 @@ h2. 3.6.8
 
 h3. Changes
   * Removed <code>@opts</code>.
-  * Deprecated @#options@ in favour of state-args. 
+  * Deprecated @#options@ in favour of state-args.
 
 h2. 3.6.7
 
 h3. Changes
-  * Added @view_assigns@ to TestCase. 
-  
+  * Added @view_assigns@ to TestCase.
+
 h2. 3.6.6
 
 h3. Changes
   * Added the @:format@ option for @#render@ which should be used with caution. Sorry for that.
-  * Removed the useless @layouts/@ view path from Cell::Base. 
+  * Removed the useless @layouts/@ view path from Cell::Base.
 
 h2. 3.6.5
 
@@ -79,7 +87,7 @@ h3. Bugfixes
   * `Cell::TestCase#invoke` now properly accepts state-args.
 
 h3. Changes
-  * Added the `:if` option to `Base.cache` which allows adding a conditional proc or instance method to the cache definition. If it doesn't return true, caching for that state is skipped. 
+  * Added the `:if` option to `Base.cache` which allows adding a conditional proc or instance method to the cache definition. If it doesn't return true, caching for that state is skipped.
 
 
 h2. 3.6.4
@@ -122,7 +130,7 @@ h3. Changes
 
 
 h2. 3.5.5
-  
+
 h3. Bugfixes
   * The generator now places views of namespaced cells into the correct directory. E.g. `rails g Blog::Post display` puts views to `app/cells/blog/post/display.html.erb`.
 
@@ -131,7 +139,7 @@ h3. Changes
 
 
 h2. 3.5.4
-  
+
 h3. Bugfixes
   * state-args work even if your state method receives optional arguments or default values, like @def show(user, age=18)@.
 
@@ -142,7 +150,7 @@ h3. Changes
 
 
 h2. 3.5.2
-  
+
 h3. Bugfixes
   * Controller#render_cell now accepts multiple args as options.
 
@@ -155,7 +163,7 @@ h2. 3.5.1
   * No longer pass an explicit Proc but a versioner block to @Cell.Base.cache@. Example: @cache :show do "v1" end@
   * Caching.cache_key_for now uses @ActiveSupport::Cache.expand_cache_key@. Consequently, a key which used to be like @"cells/director/count/a=1/b=2"@ now is @cells/director/count/a=1&b=2@ and so on. Be warned that this might break your home-made cache expiry.
   * Controller#expire_cell_state now expects the cell class as first arg. Example: @expire_cell_state(DirectorCell, :count)@
-  
+
 h3. Bugfixes
   * Passing options to @render :state@ in views finally works: @render({:state => :list_item}, item, i)@
 
@@ -165,26 +173,26 @@ h2. 3.5.0
 h3. Changes
   * Deprecated @opts, use #options now.
   * Added state-args. State methods can now receive the options as method arguments. This should be the prefered way of parameter exchange with the outer world.
-  * #params, #request, and #config is now delegated to @parent_controller. 
+  * #params, #request, and #config is now delegated to @parent_controller.
   * The generator now is invoked as @rails g cell ...@
     * The `--haml` option is no longer available.
     * The `-t` option now is compatible with the rest of rails generators, now it is used as alias for `--test-framework`. Use the `-e` option	as an alias of `--template-engine`
     Thanks to Jorge Calás Lozano <calas@qvitta.net> for patching this in the most reasonable manner i could imagine.
   * Privatized @#find_family_view_for_state@, @#render_view_for@, and all *ize methods in Cell::Rails.
   * New signature: @#render_view_for(state, *args)@
-  
+
 h2. 3.4.4
 
 h3. Changes
   * Cells.setup now yields Cell::Base, so you can really call append_view_path and friends here.
   * added Cell::Base.build for streamlining the process of deciders around #render_cell, "see here":http://nicksda.apotomo.de/2010/12/pragmatic-rails-thoughts-on-views-inheritance-view-inheritance-and-rails-304
   * added TestCase#in_view to test helpers in a real cell view.
-  
+
 
 h2. 3.4.3
 
 h3. Changes
   * #render_cell now accepts a block which yields the cell instance before rendering.
-  
+
 h3. Bugfixes
   * We no longer use TestTaskWithoutDescription in our rake tasks.

data/Gemfile

@@ -1,4 +1,4 @@
-source :gemcutter
+source 'https://rubygems.org'
 
 gemspec
 

data/README.md

@@ -0,0 +1,412 @@
+# Cells
+
+**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?
+
+No. That sucks. Take Cells.
+
+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.
+
+And the best: You can have as many cells in your page as you need!
+
+
+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.
+
+## Installation
+
+It's a gem!
+
+Rails >= 3.0:
+
+```shell
+gem install cells
+```
+
+Rails 2.3:
+
+```shell
+gem install cells -v 3.3.9
+```
+
+## Generate
+
+Creating a cell is nothing more than
+
+```shell
+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.
+
+## Render the cell
+
+Now, render your cart. Why not put it in `layouts/application.html.erb` for now?
+
+```erb
+<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.
+
+## Code
+
+Time to improve our cell code. Let's start with `app/cells/cart_cell.rb`:
+
+```ruby
+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`.
+
+
+## Views
+
+Since a plain call to `#render` will start rendering `app/cells/cart/show.html.haml` we should put some meaningful markup there.
+
+```haml
+#cart
+  You have #{@items.size} items in your shopping cart.
+```
+
+### ERB? Haml? Builder?
+
+Yes, Cells support all template types that are supported by Rails itself. Remember- it's a controller!
+
+### Helpers
+
+Yes, Cells have helpers just like controllers. If you need some specific helper, do
+
+```ruby
+class CartCell < Cell::Rails
+  helper MyExtraHelper
+```
+
+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.
+
+```haml
+%p
+  = render :view => 'items'
+```
+
+### 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"
+```
+
+
+## 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.
+
+### 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
+
+Cells do strict view caching. No cluttered fragment caching. Add
+
+```ruby
+class CartCell < Cell::Rails
+  cache :show, :expires_in => 10.minutes
+```
+
+and your cart will be re-rendered after 10 minutes.
+
+You can expand the state's cache key - why not use a versioner block to do just this?
+
+```ruby
+class CartCell < Cell::Rails
+  cache :show do |cell, options|
+    options[:items].md5
+  end
+```
+
+The block's return value is appended to the state key: `"cells/cart/show/0ecb1360644ce665a4ef"`.
+
+Check the [API to learn more](http://rdoc.info/gems/cells/Cell/Caching/ClassMethods#cache-instance_method).
+
+*Reminder*: 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
+
+## Testing
+
+Another big advantage compared to monolithic controller/helper/partial piles is the ability to test your cells isolated.
+
+### Test::Unit
+
+So what if you wanna test the cart cell? Use the generated `test/cells/cart_cell_test.rb` test.
+
+```ruby
+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
+
+```shell
+rake test:cells
+```
+
+That's easy, clean and strongly improves your component-driven software quality. How'd you do that with partials?
+
+
+### RSpec
+
+If you prefer RSpec examples, use the [rspec-cells](http://github.com/apotonick/rspec-cells) gem for specing.
+
+```ruby
+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!
+
+```shell
+rake spec:cells
+```
+
+# View Models
+
+Cells 3.9 brings a new dialect to cells: view models (still experimental!).
+
+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 Cell::Rails::ViewModel
+
+  property :title
+
+
+  def show
+    render
+  end
+
+  def self_link
+    link_to(title, song_url(model))
+  end
+end
+```
+
+### Creation
+
+Creating the view model should usually happen in the controller.
+
+```ruby
+class DashboardController < ApplicationController
+
+  def index
+    @song = Song.find(1)
+
+    @cell = cell(:song, @song)
+  end
+```
+
+You can now grab an instance of your cell using the `#cell` method. The 2nd argument will be the cell's decorated model.
+
+Have a look at how to use this cell in your controller view.
+
+```haml
+= @cell.show # renders its show view.
+```
+
+You no longer use the `#render_cell` helper but call any method on that cell. Usually, this is a state (or "action") like `show`.
+
+### Helpers
+
+Note that this doesn't have to be a rendering state, it could be any instance method (aka "helper").
+
+```haml
+= @cell.self_link
+```
+
+As all helpers are now instance methods, the `#self_link` example can use any existing helper (as the URL helpers) on the instance level.
+
+Attributes declared using ``::property` are automatically delegated to the decorated model.
+
+```ruby
+@cell.title # delegated to @song.title
+```
+
+### Views
+
+This greatly reduces wiring in the cell view (which is still in `app/cells/song/show.haml`).
+
+```haml
+%h1
+  = title
+
+Bookmark! #{self_link}
+```
+
+Making the cell instance itself the view context should be an interesting alternative for many views.
+
+
+## Mountable Cells
+
+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.
+
+```ruby
+class PostCell < Cell::Base
+  ...
+end
+```
+
+In your `routes.rb` file, mount the cell like a Rack app.
+
+```ruby
+match "/posts" => proc { |env|
+  [ 200, {}, [ Cell::Base.render_cell_for(:post, :show) ]]
+}
+```
+
+### 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.
+
+## 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!
+
+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.
+
+## Generators
+
+By default, generated cells inherit from `Cell::Rails`. If you want to change this, specify your new class name in `config/application.rb`:
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+    config.generators do |g|
+      g.base_cell_class "ApplicationCell"
+    end
+  end
+end
+```
+
+## Rails 2.3 note
+
+In order to copy the cells rake tasks to your app, run
+
+```shell
+script/generate cells_install
+```
+
+## Capture Support
+
+If you need a global `#content_for` use the [cells-capture](https://github.com/apotonick/cells-capture) gem.
+
+## More features
+
+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!
+
+
+## LICENSE
+
+Copyright (c) 2007-2013, Nick Sutterer
+
+Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
+
+Released under the MIT License.