cells 4.0.5 → 4.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9ef7b3e4ead686e4d02d8e9baf632e8333fae1bf
-  data.tar.gz: 6971a3c4628a18d399011179b922f5423ffed4d2
+  metadata.gz: d5b5b3fb59b494665fdfbed8d2f584451fbfcdaf
+  data.tar.gz: 2f803c45dcf7e60a5ce760ba62bf27a206c671e2
 SHA512:
-  metadata.gz: 786ee96506dc6cf01ec325c3b06ea78b8543f33207b756db8c18a1c96230a8eedf2394ffce08a8baa08d354a3388a3b6c4ca6a227c4bf9a237be1930265eca91
-  data.tar.gz: 58b053d459be2071faa1e09f872fb1c5b894e8a5bb14180f40f130c626fca9072750158c8894eb6e2810da44b7f6188f566c44e260b660129ea7aa59497a1ffc
+  metadata.gz: f36438868b22eac626e664baeb82bc88693a88dfaf681e7185f7636299139311c39ca05d7f1166f8768dcd2f0058ee7289d0a196b2d7d0fc1b81ce7484d68934
+  data.tar.gz: a853d11bdbb5c1b1120e085662a5ea4af833b6aac9289cba46a555ee472a3eda57e2c0ab6733ea2cd454e883c5facb4cafdd1305420a75e834f15dd833807fe4

data/.travis.yml

@@ -1,26 +1,14 @@
 language: ruby
 rvm:
   - ruby-head
+  # - 2.3
   - 2.2
   - 2.1
-  - 2.0.0
-  - 1.9.3
-  - jruby-19mode
+  - 2.0
 
 sudo: false
-
 cache: bundler
 
-bundler_args: '--without local_development --jobs 3 --retry 3'
-
-script: bundle exec rake
-
-gemfile:
-  - gemfiles/rails4.2.gemfile
-  - gemfiles/rails4.1.gemfile
-  - gemfiles/rails4.0.gemfile
-  - gemfiles/rails3.2.gemfile
-
 matrix:
   fast_finish: true
   allow_failures:

data/CHANGES.md

@@ -1,20 +1,30 @@
 ## 4.1.0
 
-TODO: extract internal :layout, extract builder
-
 ### API Fix/Changes
 
-* You can no longer pass a block to `ViewModel#call`. Use `tap` if you want the same behavior.
+* All Rails code removed. Make sure to use [Cells-rails](https://github.com/trailblazer/cells-rails) if you want the old Rails behavior.
+* A basic, rendering `#show` method is now provided automatically.
+* `ViewModel#render` now accepts a block that can be `yield`ed in the view.
+* Passing a block to `ViewModel#call` changed. Use `tap` if you want the "old" behavior (which was never official or documented).
     ```ruby
     Comment::Cell.new(comment).().tap { |cell| }
     ```
+    The new behavior is to pass that block to your state method. You can pass it on to `render`, and then `yield` it in the template.
+
+    ```ruby
+    def show(&block)
+      render &block # yield in show.haml
+    end
+    ```
+
+    Note that this happens automatically in the default `ViewModel#show` method.
 * `Concept#cell` now will resolve a concept cell (`Song::Cell`), and not the old-style suffix cell (`SongCell`). The same applies to `Concept#concept`.
 
     ```ruby
     concept("song/cell", song).cell("song/cell/composer") #=> resolves to Song::Cell::Composer
     ```
-    This decision has been made in regards of the upcoming, ass-kicking Cells 5. It simplifies code dramatically, and we consider it unnatural to mix concept and suffix cells in applications.
-* In case you were using `@parent_controller`, this doesn't exist anymore (and was never documented, either). Use `options[:context][:controller]`.
+    This decision has been made in regards of the upcoming Cells 5. It simplifies code dramatically, and we consider it unnatural to mix concept and suffix cells in applications.
+* In case you were using `@parent_controller`, this doesn't exist anymore (and was never documented, either). Use `context[:controller]`.
 * `::self_contained!` is no longer included into `ViewModel`. Please try using `Trailblazer::Cell` instead. If you still need it, here's how.
 
     ```ruby
@@ -22,11 +32,12 @@ TODO: extract internal :layout, extract builder
       extend SelfContained
       self_contained!
     ```
-
-* `Cell::Concept` is deprecated and you should be using the excellent `Trailblazer::Cell` class instead, because that's what a concept cell tries to be in an awkward way. The latter is usable without Trailblazer.
+* `Cell::Concept` is deprecated and you should be using the excellent [`Trailblazer::Cell`](https://github.com/trailblazer/trailblazer-cells) class instead, because that's what a concept cell tries to be in an awkward way. The latter is usable without Trailblazer.
 
     We are hereby dropping support for `Cell::Concept` (it still works).
 
+* Deprecating `:collection_join` and `:method` for collections.
+
 ### Awesomeness
 
 * Introduced the concept of a context object that is being passed to all nested cells. This object is supposed to contain dependencies such as `current_user`, in Rails it contains the "parent_controller" under the `context[:controller]` key.
@@ -49,6 +60,22 @@ TODO: extract internal :layout, extract builder
     ```ruby
     cell(Song::Cell, song)
     ```
+* New API for `:collection`. If used in views, this happens automatically, but here's how it works now.
+
+    ```ruby
+    cell(:comment, collection: Comment.all).() # will invoke show.
+    cell(:comment, collection: Comment.all).(:item) # will invoke item.
+    cell(:comment, collection: Comment.all).join { |cell, i| cell.show(index: i) }
+    ```
+    Basically, a `Collection` instance is returned that optionally allows to invoke each cell manually.
+* Layout cells can now be injected to wrap the original content.
+    ```ruby
+    cell(:comment, Comment.find(1), layout: LayoutCell)
+    ```
+
+    The LayoutCell will be instantiated and the `show` state invoked. The content cell's content is passed as a block, allowing the layout's view to `yield`.
+
+    This works with `:collection`, too.
 
 ## 4.0.5
 

data/Gemfile

@@ -1,8 +1,8 @@
 source "https://rubygems.org"
 
-gem "railties", "~> 4.2.0"
-gem "activemodel", "~> 4.2.0"
 gem "minitest", "~> 5.2"
 gem "cells-erb"#, path: "../cells-erb"
+gem "benchmark-ips"
+gem "minitest-line"
 
 gemspec

data/README.md

@@ -2,16 +2,23 @@
 
 *View Components for Ruby and Rails.*
 
+[![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+[![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
+[![Build
+Status](https://travis-ci.org/apotonick/cells.svg)](https://travis-ci.org/apotonick/cells)
+[![Gem Version](https://badge.fury.io/rb/cells.svg)](http://badge.fury.io/rb/cells)
+
 ## Overview
 
 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](#nested-cells), view inheritance, using Rails helpers, [asset packaging](http://trailblazer.to/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!
+## Full Documentation
 
-Temporary note: This is the README and API for Cells 4. Many things have improved. If you want to upgrade, [follow this guide](https://github.com/apotonick/cells/wiki/From-Cells-3-to-Cells-4---Upgrading-Guide). When in trouble, join us on the IRC (Freenode) #trailblazer channel.
+Cells is part of the Trailblazer framework. [Full documentation](http://trailblazer.to/gems/cells) is available on the project site.
 
+Cells is completely decoupled from Rails. However, Rails-specific functionality is to be found [here](http://trailblazer.to/gems/cells/rails.html).
 
 ## Rendering Cells
 
@@ -184,7 +191,8 @@ 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) Make sure to bundle Haml 4.1: `gem "haml", github: "haml/haml", ref: "7c7c169"`.
+* [cells-hamlit](https://github.com/trailblazer/cells-hamlit) We strongly recommend using [Hamlit](https://github.com/k0kubun/hamlit) as a Haml replacement.
+* [cells-haml](https://github.com/trailblazer/cells-haml) Make sure to bundle Haml 4.1: `gem "haml", github: "haml/haml", ref: "7c7c169"`. Use `cells-hamlit` instead.
 * [cells-slim](https://github.com/trailblazer/cells-slim)
 
 ```ruby
@@ -195,25 +203,10 @@ In Rails, this is all you need to do. In other environments, you need to include
 
 ```ruby
 class CommentCell < Cell::ViewModel
-  include ::Cell::Erb # or Cell::Haml, or Cell::Slim
+  include ::Cell::Erb # or Cell::Hamlit, or Cell::Haml, or Cell::Slim
 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`.
@@ -370,33 +363,7 @@ This works both in cell views and on the instance, in states.
 
 ## View Inheritance
 
-Cells can inherit code from each other with Ruby's inheritance.
-
-```ruby
-class CommentCell < Cell::ViewModel
-end
-
-class PostCell < CommentCell
-end
-```
-
-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"]
-```
+You can not only inherit code across cell classes, but also views. This is extremely helpful if you want to override parts of your UI, only. It's [documented here](http://trailblazer.to/gems/cells/api.html#view-inheritance).
 
 ## Collections
 
@@ -407,7 +374,7 @@ comments = Comment.all #=> three comments.
 cell(:comment, collection: comments)
 ```
 
-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`.
+This will invoke `cell(:comment, comment).()` three times and concatenate the rendered output automatically. In case you don't want `show` but another state rendered, use `:method`.
 
 ```ruby
 cell(:comment, collection: comments, method: :list)
@@ -457,7 +424,6 @@ For every cell class you can define caching per state. Without any configuration
 ```ruby
 class CommentCell < Cell::ViewModel
   cache :show
-
   # ..
 end
 ```
@@ -468,20 +434,12 @@ The `::cache` method will forward options to the caching engine.
 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}" }
-```
-
-Caching is documented [here](http://trailblazer.to/gems/cells/caching.html) and in chapter 8 of the [Trailblazer book](http://leanpub.com/trailblazer).
+You can also compute your own cache key, use dynamic keys, cache tags, and conditionals using `:if`. Caching is documented [here](http://trailblazer.to/gems/cells/api.html#caching) and in chapter 8 of the [Trailblazer book](http://leanpub.com/trailblazer).
 
 
 ## 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.
+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 many use cases of Cells.
 
 <a href="https://leanpub.com/trailblazer">
 ![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
@@ -493,39 +451,11 @@ Cells is part of the [Trailblazer project](https://github.com/apotonick/trailbla
 * Cells Pagination with AJAX (chapter 6).
 * View Caching and Expiring (chapter 8).
 
-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.
 
+## This is not Cells 3.x!
 
-## Undocumented Features
-
-*(Please don't read this section!)*
-
-### Rendering Global Partials
-
-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.
-
-This works by including `Partial` and the corresponding `:partial` option.
-
-```ruby
-class Cell < Cell::ViewModel
-  include Partial
-
-  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.
+Temporary note: This is the README and API for Cells 4. Many things have improved. If you want to upgrade, [follow this guide](https://github.com/apotonick/cells/wiki/From-Cells-3-to-Cells-4---Upgrading-Guide). When in trouble, join us on the IRC (Freenode) #trailblazer channel.
 
 ## LICENSE
 

data/benchmarks/class_builder.rb

@@ -0,0 +1,37 @@
+require 'bundler/setup'
+require 'benchmark/ips'
+require "cells"
+require 'cell/view_model'
+
+class ACell < Cell::ViewModel
+  def show
+    ""
+  end
+end
+
+class ACellWithBuilder < Cell::ViewModel
+  include Cell::Builder
+
+  def show
+    ""
+  end
+end
+
+Benchmark.ips do |x|
+  x.report("ACell") { ACell.().() }
+  x.report("ACellWithBuilder") { ACellWithBuilder.().() }
+  x.compare!
+end
+
+__END__
+
+Calculating -------------------------------------
+               ACell    25.710k i/100ms
+    ACellWithBuilder    19.948k i/100ms
+-------------------------------------------------
+               ACell    419.631k (± 5.0%) i/s -      2.108M
+    ACellWithBuilder    291.924k (± 5.7%) i/s -      1.476M
+
+Comparison:
+               ACell:   419630.8 i/s
+    ACellWithBuilder:   291923.5 i/s - 1.44x slower

data/benchmarks/collection.rb

@@ -0,0 +1,47 @@
+require 'test_helper'
+require 'benchmark'
+require 'benchmark/ips'
+
+Song = Struct.new(:title)
+
+
+class SongCell < Cell::ViewModel
+  self.view_paths = ['test/fixtures']
+  property :title
+
+  def show
+    render
+  end
+end
+
+ary = 1000.times.collect { |i| Song.new(i) }
+
+Benchmark.ips do |x|
+  x.report("collection, call") { SongCell.(collection: ary).() }
+  x.report("collection, join") { SongCell.(collection: ary).join { |cell, i| cell.() } }
+  # x.report("collection, joinstr") { SongCell.(collection: ary).joinstr { |cell, i| cell.() } }
+  # x.report("collection, joincollect") { SongCell.(collection: ary).joincollect { |cell, i| cell.() } }
+  # x.report("ACellWithBuilder") { ACellWithBuilder.().() }
+  x.compare!
+end
+
+__END__
+
+Calculating -------------------------------------
+    collection, call     3.000  i/100ms
+    collection, join     3.000  i/100ms
+-------------------------------------------------
+    collection, call     33.403  (± 3.0%) i/s -    168.000
+    collection, join     33.248  (± 3.0%) i/s -    168.000
+
+Comparison:
+    collection, call:       33.4 i/s
+    collection, join:       33.2 i/s - 1.00x slower
+
+
+
+Comparison:
+    collection, join:       32.8 i/s
+    collection, call:       32.6 i/s - 1.01x slower
+ collection, joinstr:       32.6 i/s - 1.01x slower
+collection, joincollect:       32.4 i/s - 1.01x slower # each_with_index.collect.join

data/cells.gemspec

@@ -1,7 +1,7 @@
-lib = File.expand_path('../lib/', __FILE__)
+lib = File.expand_path("../lib/", __FILE__)
 $:.unshift lib unless $:.include?(lib)
 
-require 'cell/version'
+require "cell/version"
 
 Gem::Specification.new do |spec|
   spec.name        = "cells"
@@ -12,19 +12,17 @@ Gem::Specification.new do |spec|
   spec.homepage    = "https://github.com/apotonick/cells"
   spec.summary     = %q{View Models for Ruby and Rails.}
   spec.description = %q{Cells replaces partials and helpers with OOP view models, giving you proper encapsulation, inheritance, testability and a cleaner view architecture.}
-  spec.license     = 'MIT'
+  spec.license     = "MIT"
 
   spec.files         = `git ls-files`.split("\n")
   spec.test_files    = `git ls-files -- {test}/*`.split("\n")
   spec.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "uber",        "~> 0.0.9"
-  spec.add_dependency 'tilt', '>= 1.4', '< 3'
+  spec.add_dependency "uber", ">= 0.0.9"
+  spec.add_dependency "tilt", ">= 1.4", "< 3"
 
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest-reporters"
   spec.add_development_dependency "capybara"
-
   spec.add_development_dependency "cells-erb", ">= 0.0.4"
 end

data/lib/cell.rb

@@ -4,13 +4,8 @@ require "uber/delegates"
 require "cell/version"
 
 module Cell
-  autoload :TestCase, "cell/test_case"
   autoload :Testing,  "cell/testing"
 
-  def self.rails_version
-    Gem::Version.new(ActionPack::VERSION::STRING)
-  end
-
   class TemplateMissingError < RuntimeError
     def initialize(prefixes, view)
       super("Template missing: view: `#{view.to_s}` prefixes: #{prefixes.inspect}")
@@ -19,10 +14,7 @@ module Cell
 end
 
 require "cell/caching"
-require "cell/caching/notification"
-require "uber/builder"
 require "cell/prefixes"
-require "cell/self_contained"
 require "cell/layout"
 require "cell/templates"
 require "cell/abstract"
@@ -30,6 +22,5 @@ require "cell/util"
 require "cell/view_model"
 require "cell/concept"
 require "cell/escaped"
-
-
-require "cell/railtie" if defined?(Rails)
+require "cell/builder"
+require "cell/collection"