cells 3.11.1 → 3.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c53e5fa8e782efe252f69d45eb54744307783f3
-  data.tar.gz: 011cdedbdaacfed0a06b8cdbddbec0e7d2cd8745
+  metadata.gz: c9fb9e1377ed4ea72e0d162fd29e524e0f9b67b6
+  data.tar.gz: b661b6b504610a68198751905d6b186ed18c0dbb
 SHA512:
-  metadata.gz: 69598d8a734a02879d669d80a0c992eb112f4fb93b09acb7ab6825a2239e802510fa0a32a81cc83956963c838eda5859610cce115b67b8a6aea14d387f55c2f7
-  data.tar.gz: 425bd7009da186564e92bb54cfeec06d950be7704947c66a5a4cb113f957807a482ef54eaab399bc3872e2ddb1480cfaa876cb4c314053f3512dcba061e38370
+  metadata.gz: a6d39c7b449b5f8ab11973e953dee4895e1aa062e086449e1bf477214235b6a72fa8a450e91aaee9bbd8d559b71cb1d5eb6ea9559d0d0a9f0376be1a9f5e64b1
+  data.tar.gz: 3acac5e4ef165a75ea79763c5db07b450d128aaa44a438588aa29f3c69d55e642a6e8567234812cd46bd6893058d69538709cf85c242de6c4c175dc3c3d5ad82

data/CHANGES.md

@@ -1,3 +1,11 @@
+## 3.11.2
+
+* `ViewModel#call` now accepts a block and yields `self` (the cell instance) to it. This is handy to use with `content_for`.
+    ```ruby
+      = cell(:song, Song.last).call(:show) do |cell|
+        content_for :footer, cell.footer
+    ```
+
 ## 3.11.1
 
 * Override `ActionView::Helpers::UrlHelper#url_for` in Rails 4.x as it is troublesome. That removes the annoying

data/Gemfile

@@ -6,3 +6,7 @@ gemspec
 
 gem "rails", "~> 3.2.12"
 gem 'minitest', '4.7.5'
+
+# gem 'uber', :path => "../uber"
+
+gem 'disposable', path: '../disposable'

data/README.md

@@ -14,13 +14,15 @@ Basically, cells can be rendered anywhere in your code. Most people use them in
 
 ## View Models
 
-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.
+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.
 
 While the old dialect still works, we strongly recommend using a cell as a view model.
 
 
 ## Installation
 
+Cells run with all Rails >= 3.0. For 2.3 support [see below](#rails-23-note).
+
 ```ruby
 gem 'cells'
 ```
@@ -214,8 +216,14 @@ Sometimes you need to render a global partial from `app/views` within a cell. Fo
 ```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
 
@@ -510,6 +518,96 @@ end
 
 You can now safely use `#title` in the view (and, in the cell class), it is delegated to `model.title`.
 
+### 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
+```
+
+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
+
+  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
+
+You create your cell as follows.
+
+```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.
+
+```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.
+
+```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
+```
+
+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.

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.6"
+  s.add_dependency "uber",        "~> 0.0.8"
 
   s.add_development_dependency "rake"
   s.add_development_dependency "haml"
@@ -31,4 +31,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "activemodel"
   s.add_development_dependency "capybara"
   s.add_development_dependency "sprockets"
+  s.add_development_dependency "disposable", "~> 0.0.6"
 end

data/lib/cell/twin.rb

@@ -0,0 +1,38 @@
+require 'disposable/twin'
+require 'disposable/twin/option'
+module Cell
+  class Twin < Disposable::Twin
+    include Option
+
+    def self.property_names
+      representer_class.representable_attrs.collect(&:name)
+    end
+
+    module Properties
+      def self.included(base)
+        base.extend Uber::InheritableAttr
+        base.inheritable_attr :twin_class
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def properties(twin_class)
+          twin_class.property_names.each { |name| property name }
+          self.twin_class = twin_class
+        end
+
+        alias_method :twin, :properties
+      end
+
+      def initialize(controller, model, options={})
+        super(controller, build_twin(model, options))
+      end
+
+    private
+
+      def build_twin(*args)
+        self.class.twin_class.new(*args)
+      end
+    end
+  end
+end

data/lib/cell/view_model.rb

@@ -5,11 +5,14 @@
 # call "helpers" in class
 
 # TODO: warn when using ::property but not passing in model in constructor.
+require 'uber/delegates'
 
 # ViewModel is only supported in Rails +3.1. If you need it in Rails 3.0, let me know.
 class Cell::ViewModel < Cell::Rails
   abstract!
 
+  extend Uber::Delegates
+
   include Cell::OptionsConstructor
   #include ActionView::Helpers::UrlHelper
   include ActionView::Context # this includes CompiledTemplates, too.
@@ -39,7 +42,7 @@ class Cell::ViewModel < Cell::Rails
 
   class << self
     def property(*names)
-      delegate *names, :to => :model
+      delegates :model, *names # Uber::Delegates.
     end
 
     include Helpers
@@ -55,20 +58,21 @@ class Cell::ViewModel < Cell::Rails
     _prepare_context # happens in AV::Base at the bottom.
   end
 
+  # render :show
   def render(options={})
-    if options.is_a?(Hash)
-      options.reverse_merge!(:view => state_for_implicit_render)
-    else
-      options = {:view => options.to_s}
-    end
+    options = options_for(options, caller) # TODO: call render methods with call(:show), call(:comments) instead of directly #comments?
 
     super
   end
 
+  # Invokes the passed state (defaults to :show) by using +render_state+. This will respect caching.
+  # Yields +self+ (the cell instance) to an optional block.
   def call(state=:show)
     # it is ok to call to_s.html_safe here as #call is a defined rendering method.
     # DISCUSS: IN CONCEPT: render( view: implicit_state)
-    render_state(state).to_s.html_safe
+    content = render_state(state)
+    yield self if block_given?
+    content.to_s.html_safe
   end
 
 private
@@ -76,8 +80,16 @@ private
     self
   end
 
-  def state_for_implicit_render()
-    caller[1].match(/`(\w+)/)[1]
+  def options_for(options, caller)
+    if options.is_a?(Hash)
+      options.reverse_merge(:view => state_for_implicit_render(caller)) # TODO: test implicit render!
+    else
+      {:view => options.to_s}
+    end
+  end
+
+  def state_for_implicit_render(caller)
+    caller[0].match(/`(\w+)/)[1]
   end
 
   # def implicit_state

data/lib/cells/version.rb

@@ -1,3 +1,3 @@
 module Cells
-  VERSION = '3.11.1'
+  VERSION = '3.11.2'
 end

data/test/rails/view_model_test.rb

@@ -81,12 +81,20 @@ if Cell.rails_version >= 3.1
 
       attr_accessor :count
       cache :count
+
+      def title
+        super.upcase
+      end
     end
 
-    let (:song) { Song.new(:title => "65", artist: "Boss") }
-    it { HitCell.new(nil, song).title.must_equal "65" }
+    let (:song) { Song.new(:title => "Sixtyfive", artist: "Boss") }
+
+    # ::property creates accessor.
     it { HitCell.new(nil, song).artist.must_equal "Boss" }
 
+    # ::property accessor can be overridden and call super.
+    it { HitCell.new(nil, song).title.must_equal "SIXTYFIVE" }
+
 
     describe "#call" do
       let (:cell) { HitCell.new(nil, song) }
@@ -118,6 +126,15 @@ if Cell.rails_version >= 3.1
         cell.count = 2
         cell.call(:count).must_equal "1"
       end
+
+      # call(:show) do .. end
+      it do
+        cell.call(:show) do |c|
+          c.instance_variable_set(:@volume, 9)
+        end.must_equal "Great!"
+
+        cell.instance_variable_get(:@volume).must_equal 9
+      end
     end
 
 

data/test/twin_test.rb

@@ -0,0 +1,30 @@
+require 'test_helper'
+require 'cell/twin'
+
+if Cell.rails_version >= 3.1
+
+class TwinTest < MiniTest::Spec
+  class SongCell < Cell::ViewModel
+    class Twin < Cell::Twin
+      property :title
+      option :online?
+    end
+
+    include Cell::Twin::Properties
+    properties Twin
+
+    def show
+      "#{title} is #{online?}"
+    end
+
+    def title
+      super.downcase
+    end
+  end
+
+  let (:model) { OpenStruct.new(:title => "Kenny") }
+
+  it { SongCell.new(nil, model, :online? => true).call.must_equal "kenny is true" }
+end
+
+end

metadata

@@ -1,169 +1,183 @@
 --- !ruby/object:Gem::Specification
 name: cells
 version: !ruby/object:Gem::Version
-  version: 3.11.1
+  version: 3.11.2
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-31 00:00:00.000000000 Z
+date: 2014-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: uber
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.0.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.0.8
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: haml
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: slim
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.7.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.7.5
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sprockets
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: disposable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.6
 description: Cells are view components for Rails. They are lightweight controllers,
   can be rendered in views and thus provide an elegant and fast way for encapsulation
   and component-orientation.
@@ -173,8 +187,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - CHANGES.md
 - Gemfile
 - README.md
@@ -206,6 +220,7 @@ files:
 - lib/cell/rails4_1_strategy.rb
 - lib/cell/rendering.rb
 - lib/cell/test_case.rb
+- lib/cell/twin.rb
 - lib/cell/view_model.rb
 - lib/cells.rb
 - lib/cells/cells.rake
@@ -336,6 +351,7 @@ files:
 - test/self_contained_test.rb
 - test/test_case_test.rb
 - test/test_helper.rb
+- test/twin_test.rb
 homepage: http://cells.rubyforge.org
 licenses:
 - MIT
@@ -346,18 +362,121 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.2.1
 signing_key: 
 specification_version: 4
 summary: View Components for Rails.
-test_files: []
+test_files:
+- test/app/cells/album/views/cover.haml
+- test/app/cells/bad_guitarist/_dii.html.erb
+- test/app/cells/bad_guitarist_cell.rb
+- test/app/cells/bassist/_dii.html.erb
+- test/app/cells/bassist/ahem.html.erb
+- test/app/cells/bassist/compose.html.erb
+- test/app/cells/bassist/contact_form.html.erb
+- test/app/cells/bassist/form_for.erb
+- test/app/cells/bassist/form_for_in_haml.haml
+- test/app/cells/bassist/jam.html.erb
+- test/app/cells/bassist/play.html.erb
+- test/app/cells/bassist/play.js.erb
+- test/app/cells/bassist/pose.html.erb
+- test/app/cells/bassist/promote.html.erb
+- test/app/cells/bassist/provoke.html.erb
+- test/app/cells/bassist/shout.html.erb
+- test/app/cells/bassist/sing.html.haml
+- test/app/cells/bassist/slap.html.erb
+- test/app/cells/bassist/yell.en.html.erb
+- test/app/cells/bassist_cell.rb
+- test/app/cells/club_security.rb
+- test/app/cells/club_security/guard/help.html.erb
+- test/app/cells/club_security/guard_cell.rb
+- test/app/cells/club_security/medic/help.html.erb
+- test/app/cells/club_security/medic_cell.rb
+- test/app/cells/layouts/b.erb
+- test/app/cells/layouts/metal.html.erb
+- test/app/cells/rails_helper_api_test/bassist/edit.html.erb
+- test/app/cells/shouter/sing.html.erb
+- test/app/cells/song/dashboard.haml
+- test/app/cells/song/details.html.haml
+- test/app/cells/song/info.html.haml
+- test/app/cells/song/lyrics.html.haml
+- test/app/cells/song/plays.haml
+- test/app/cells/song/scale.haml
+- test/app/cells/song/show.html.haml
+- test/app/cells/song/title.html.haml
+- test/app/cells/trumpeter/promote.html.erb
+- test/app/cells/trumpeter_cell.rb
+- test/app/cells/view_model_test/comments/show.haml
+- test/app/concepts/record/views/layout.haml
+- test/app/concepts/record/views/show.erb
+- test/app/concepts/record/views/song.erb
+- test/app/views/shared/_dong.html.erb
+- test/cell_generator_test.rb
+- test/cell_module_test.rb
+- test/cell_test.rb
+- test/cells_module_test.rb
+- test/concept_generator_test.rb
+- test/concept_test.rb
+- test/deprecations_test.rb
+- test/dummy/Rakefile
+- test/dummy/app/assets/javascripts/application.js
+- test/dummy/app/cells/album/assets/album.js
+- test/dummy/app/concepts/song/assets/songs.js
+- test/dummy/app/controllers/application_controller.rb
+- test/dummy/app/helpers/application_helper.rb
+- test/dummy/app/views/layouts/application.html.erb
+- test/dummy/app/views/musician/featured.html.erb
+- test/dummy/app/views/musician/featured_with_block.html.erb
+- test/dummy/app/views/musician/hamlet.html.haml
+- test/dummy/app/views/musician/title.erb
+- test/dummy/config.ru
+- test/dummy/config/application.rb
+- test/dummy/config/boot.rb
+- test/dummy/config/database.yml
+- test/dummy/config/environment.rb
+- test/dummy/config/environments/development.rb
+- test/dummy/config/environments/production.rb
+- test/dummy/config/environments/test.rb
+- test/dummy/config/locales/en.yml
+- test/dummy/config/routes.rb
+- test/dummy/db/test.sqlite3
+- test/dummy/label/app/cells/label/show.erb
+- test/dummy/label/app/cells/label_cell.rb
+- test/dummy/label/label.gemspec
+- test/dummy/label/lib/label.rb
+- test/dummy/label/lib/label/version.rb
+- test/dummy/log/production.log
+- test/dummy/log/server.log
+- test/dummy/public/404.html
+- test/dummy/public/422.html
+- test/dummy/public/500.html
+- test/dummy/public/favicon.ico
+- test/dummy/public/stylesheets/.gitkeep
+- test/dummy/script/rails
+- test/helper_test.rb
+- test/prefixes_test.rb
+- test/rack_test.rb
+- test/rails/asset_pipeline_test.rb
+- test/rails/caching_test.rb
+- test/rails/cells_test.rb
+- test/rails/forms_test.rb
+- test/rails/integration_test.rb
+- test/rails/render_test.rb
+- test/rails/view_model_test.rb
+- test/rails/view_test.rb
+- test/rails_helper_api_test.rb
+- test/self_contained_test.rb
+- test/test_case_test.rb
+- test/test_helper.rb
+- test/twin_test.rb
+has_rdoc: