frill 0.1.8 → 0.1.9

data/VERSION

@@ -1 +1 @@
-0.1.8
+0.1.9

data/lib/frill/rails.rb

@@ -1,5 +1,25 @@
+module Frill
+  module Auto
+    protected
+
+    def view_assigns
+      new_hash = {}
+
+      super.each do |key,value|
+        new_hash[key] = frill value
+      end
+
+      new_hash
+    end
+  end
+end
+
 module ActionController
   class Base
+    def self.auto_frill
+      self.send :include, Frill::Auto
+    end
+
     helper_method :frill 
 
     private

data/readme.markdown

@@ -23,66 +23,110 @@ $ rails g frill Timestamp --test-framework=rspec
       create    spec/frills/timestamp_frill_spec.rb
 ```
 
-## Usage
+## Refactoring timestamp helpers with decorators
 
-(For the purposes of this tutorial, I'm going to assume you're using
-`frill` inside a Rails app. Checkout the `Usage outside Rails` section
-below if you're not using Rails.)
+Your product manager writes the following story for you: 
 
-Imagine you're creating a web application that includes both a
-JSON API and an HTML frontend, and you've decided to always present a
-timestamp as YEAR/MONTH/DAY. Furthermore, when presented in HTML, you
-always want your timestamps wrapped in `<b>` tags.
+```cucumber
+Feature: Consistent Timestamp Presentation
+  As a user
+  I want "created at" timestamps presented in a uniform way on the site
+  So that I can easily discover the age of content on the site
 
-This is a perfect fit for the GoF decorator pattern. Start by generating a `Timestamp` frill:
+  Scenario: Presenting timestamps
+    When I navigate to a page that displays a created_at timestamp
+    Then I should see that timestamp marked up as bold and formatted as follows: YYYY/MM/DD
+```
 
-```sh
-$ rails g frill Timestamp --test-framework=rspec
-      create  app/frills/timestamp_frill.rb
-      invoke  rspec
-      create    spec/frills/timestamp_frill_spec.rb
+You see this and roll your eyes. You're thinking about all of the places that you show `created_at` 
+timestamps on the site. Regardless you roll up your sleeves and start by writing the following helper and partial:
+
+```ruby
+module ApplicationHelper
+  def format_timestamp(t)
+    render partial: "shared/timestamp", locals: { time: t.strftime "%Y/%m/%d" }
+  end
+end
+```
+
+```erb
+<b><%=time%></b>
+```
+
+You then begin the tedious task of tracking down all of the places you render timestamps on the site and wrapping them with `format_timestamp` helper calls:
+
+```erb
+...
+Written on <%=format_timestamp @article.created_at %>
 ```
 
-You can safely leave off the `--test-framework=rspec` portion if you've configured rspec as your default framework (or
-if you're not using rspec at all).
+You hate this approach.
+
+1. It's tedious
+1. It's procedural
+1. Developers have to remember to manually wrap timestamps with your `format_timestamp` helper. Developers suck at remembering things like that. FACEPALM
+
+After you deliver the story, your product owner says "Great! But what about the format of timestamps in the JSON api? Here's another story."
+
+```cucumber
+Feature: Consistent Timestamp Presentation in the API
+  As an API consumer
+  I want "created at" timestamps presented in the API in uniform way
+  So that I can easily discover the age of data I consume
+
+  Scenario: Presenting timestamps
+    When I retrieve content with a "created_at" timestamp via the JSON API
+    Then I should see that timestamp formatted as follows: YYYY/MM/DD
+```
+
+You attempt to salvage the helper, updating it with concerns for the JSON format:
+
+```ruby
+module ApplicationHelper
+  def format_timestamp(t)
+    time = t.strftime "%Y/%m/%d" 
+
+    if request.format.html?
+      render partial: "shared/timestamp", locals: { time: time }
+    elsif request.format.json?
+      time
+    end
+  end
+end
+```
+
+And now you begin the tedious track of updating all of the JSON views with the helper:
+
+```ruby
+json.created_at format_timestamp(@article.created_at)
+```
+
+At this point, you're banging your head against a table.
+
+### Enter Frill
 
-Now open up `app/frills/timestamp_frill.rb` and format those timestamps:
+Let's refactor this using the decorator pattern. First, revert all of your changes. Next, add the `frill` gem to your Gemfile, run `bundle`, then generate a frill: `rails g frill TimestampFrill`:
 
 ```ruby
 module TimestampFrill
   include Frill
 
   def self.frill? object, context
-    object.respond_to?(:created_at) && object.respond_to?(:updated_at)
+    object.respond_to?(:created_at)
   end
 
   def created_at
-    format_time super
-  end
-
-  def updated_at
-    format_time super
-  end
-
-  private
-
-  def format_time(t)
-    t.strftime "%Y/%m/%d"
+    super.strftime "%Y/%m/%d"
   end
 end
 ```
 
-The first method `self.frill?` tells `Frill` what kind of objects this
-decorator is applicable to. In our case, it's any object that have timestamps.
+The `frill?` method tells `Frill` when to extend an object with this module. Then we redefine the `created_at` method, 
+calling super and then formatting the date returned with `strftime`.
 
-Next, let's create an `HtmlTimestampFrill` module:
+Simple enough. 
 
-```sh
-$ rails g frill HtmlTimestamp --test-framework=rspec
-      create  app/frills/html_timestamp_frill.rb
-      invoke  rspec
-      create    spec/frills/html_timestamp_frill_spec.rb
-```
+Next, generate another frill for presenting timestamps via HTML (`rails g frill HtmlTimestampFrill`):
 
 ```ruby
 module HtmlTimestampFrill
@@ -90,37 +134,24 @@ module HtmlTimestampFrill
   after TimestampFrill
 
   def self.frill? object, context
-    object.respond_to?(:created_at) &&
-    object.respond_to?(:updated_at) &&
-    context.request.format.html?
+    object.respond_to?(:created_at) && context.request.format.html?
   end
 
   def created_at
-     format_time_for_html super
-  end
-
-  def updated_at
-    format_time_for_html super
-  end
-
-  private
-  def format_time_for_html t
-    h.content_tag :b, t
+     h.render partial: "shared/timestamp", locals: { time: super }
   end
 end
 ```
 
-Two things to note: the `HtmlTimestampFrill` is only applicable to
-objects that have timestamps _when presented in "html"_. Also, we
-tell `Frill` to decorate `after` `TimestampFrill` is applied (so that
-`super` in `created_at` returns our `TimestampFrill` response).
+There's two important things to note: 
 
-Note that you can also specify decoration dependencies with `before` instead of `after`.
+1. This frill comes after `TimestampFrill`. That tells `Frill` that it should only attempt to extend an object with this module after attempting to extend it with `TimestampFrill`.
+1. The `frill?` method only returns true if it's an HTML request, meaning this frill won't be extended onto objects for your JSON api.
 
-Next, in our controller, we need to decorate our objects with frills:
+Lastly, opt objects into frilling inside your controllers: 
 
 ```ruby
-class PostsController < ApplicationController
+class ArticlesController < ApplicationController
   respond_to :json, :html
 
   def show
@@ -130,19 +161,37 @@ class PostsController < ApplicationController
 end
 ```
 
-Notice that we've wrapped our article in a `frill`.
+And that's it. You don't have to update any of your views. Why? When you call the `frill` method inside your controller and pass it an object (or a collection of objects), 
+frill will attempt to extend the object with any applicable frills (i.e., frills that return `true` for the `frill?` method when passed the object and the request context).
 
-In your html view, you simply call `@article.created_at`:
+That way, you can simple render your `created_at` attributes without any helpers, and they will automatically present themselves appropriately for their context (e.g., HTML v. JSON requests).
 
-```erb
-<%= @article.created_at %>
+Note that if prefer, you can configure your controllers to automatically frill all objects for presentation by calling the `auto_frill` method inside your `ApplicationController`, instead of manually having to opt them it via the `frill` method:
+
+```ruby
+class ApplicationController < ActionController::Base
+  auto_frill
+end
 ```
 
-The same goes for your JSON view.
+Now, you could remove the `frill` from your `ArticlesController`:
+
+```ruby
+class ArticlesController < ApplicationController
+  respond_to :json, :html
+
+  def show
+    @article = Article.find(params[:id])
+    respond_with @article
+  end
+end
+```
+
+Now, any instance variables you create in your controllers will be automatically frilled before handed off to your views.
 
 ### 'frill' decorates individual objects _and_ collections
 
-The `frill` helper will decorate both collections and associations. You can use it both within your controller
+As I've hinted at, the `frill` helper will decorate both single objects and collections of objects. You can use it both within your controller
 and within your views.
 
 For example, inside a controller: 
@@ -169,7 +218,7 @@ Or, in a view:
 
 There are really just two integrations in a Rails app: the `frill` 
 method inside of your controller, plus the ability to call 
-`ActionView::Helper` methods inside of your module methods.
+helper methods inside of your module methods.
 
 To kickoff the decoration of an object outside of a Rails application,
 simply call `Frill.decorate`:
@@ -182,15 +231,3 @@ Frill.decorate my_object, my_context
 
 * Ben Moss
 * Nicholas Greenfield
-
-## License
-
-(The MIT License)
-
-Copyright © 2012 Matt Parker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: frill
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70351976271960 !ruby/object:Gem::Requirement
+  requirement: &70096022400640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 3.2.2
   type: :development
   prerelease: false
-  version_requirements: *70351976271960
+  version_requirements: *70096022400640
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70351976271340 !ruby/object:Gem::Requirement
+  requirement: &70096022399720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70351976271340
+  version_requirements: *70096022399720
 - !ruby/object:Gem::Dependency
   name: rspec-rails
-  requirement: &70351976270520 !ruby/object:Gem::Requirement
+  requirement: &70096022399120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70351976270520
+  version_requirements: *70096022399120
 - !ruby/object:Gem::Dependency
   name: capybara
-  requirement: &70351976270000 !ruby/object:Gem::Requirement
+  requirement: &70096022398500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70351976270000
+  version_requirements: *70096022398500
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70351976269480 !ruby/object:Gem::Requirement
+  requirement: &70096022397820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70351976269480
+  version_requirements: *70096022397820
 description: 
 email: moonmaster9000@gmail.com
 executables: []