bird_on_it 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b1143de097aadc7beb49c385173ea1abc1cf75e4
-  data.tar.gz: a41af0dd48da71e3377abc6284d896cd7ea493b3
+  metadata.gz: 52177a68952ac06a60c8fcfebd8b6b93b5d3bc14
+  data.tar.gz: 5c5b3cc9e324e96b571dc5096e24c3f57dfb443e
 SHA512:
-  metadata.gz: 135f83b1db2d868ddcf240a4efbf2d32fe8b6a404a3b2afd21a522576086a20b255577396eb5e45f0b4f8133a0e5e378aa0dfe92dd64b411d3dfef3ca7b6687b
-  data.tar.gz: c4b414dd898e951e5b798e7685f47efbe49f3ba451404c1ba5598072b2dfafe94e029b46c9eaa46cd4aaf450def059798db4474e637617b1f65ab18c029d5a5c
+  metadata.gz: 3cf19d242f8313349af3ae73ad56fe4ec8be6f3dccef05ce885808b4e7c54f303f3d9572bc29d9222e93aebc75c03ff9e88604dfd3d10d248b6f658c9d91b17b
+  data.tar.gz: be11ec856d3b5d96e7df336733fe4ecf35b782512ec5ae9887c1303b2ee886c4b4a83c1556f6138af670f8429d2355137a439ce6b433ac763b4e4238f443e81b

data/README.md

@@ -0,0 +1,180 @@
+# Bird On It: Simple decorators for your Rails models
+
+Model need decorating in your Rails view? Put a bird on it!
+
+## What is Bird On It?
+
+_Bird On It_ is a simple way to decorate models in your Rails application.
+
+Decorators allow you to move view- and presentation-related logic out of your active record models and view helpers and into decorator classes. Doing this cleans up your view code and reduces the number of responsibilities your active record objects have.
+
+Here's how it works. Let's say you have a ToteBag model, with colour, size and straps attributes. In your view, you want to describe whether or not the bag has straps. You also want to add some css classes, depending on what properties the bag has. You put the first of these methods on the model, and the second in a helper, like so:
+
+```ruby
+# app/models/tote_bag.rb
+class ToteBag < ActiveRecord::Base
+  def straps_description
+    if straps?
+      'This bag has straps'
+    else
+      'This bag does not have straps'
+    end
+  end
+end
+```
+
+```ruby
+# app/helpers/tote_bags_helper.rb
+module ToteBagHelper
+  def tote_bag_css_classes(tote_bag)
+    tote_bag_css_classes = %w{tote-bag}
+    tote_bag_css_classes << 'straps' if tote_bag.straps?
+    tote_bag_css_classes.join(' ')
+  end
+end
+```
+
+In your view, you would use both the helper and model:
+
+```erb
+<div class="<%= tote_bag_css_classes(@tote_bag) %>">
+  <h2>Straps:</h2>
+  <p><%= @tote_bag.straps_description %></p>
+</div>
+```
+
+Instead of the above, however, using a tote bag decorator allows both these methods to exist in the one place. The decorator sends any method that it doesn't itself respond to the decorated object. Using _Bird On It_:
+
+```ruby
+# app/models/tote_bag.rb
+class ToteBag < ActiveRecord::Base
+  include BirdOnIt
+end
+```
+
+```ruby
+# app/decorators/tote_bag_decorator.rb
+class ToteBagDecorator
+  include BirdOnIt::Decorator
+
+  def straps_description
+    if object.straps?
+      'This bag has straps'
+    else
+      'This bag does not have straps'
+    end
+  end
+
+  def css_classes
+    css_classes = %w{tote-bag}
+    css_classes << 'straps' if object.straps?
+    css_classes.join(' ')
+  end
+end
+```
+
+In your view:
+
+```erb
+<div class="<%= @tote_bag.css_classes %>">
+  <h2>Straps:</h2>
+  <p><%= @tote_bag.straps_description %></p>
+</div>
+```
+
+Now your view-related code can reside in the decorator, eliminating the need for helper methods and giving your tote bag class one less responsibility.
+
+## Installation
+
+Add _Bird On It_ to your Gemfile
+
+```ruby
+  gem 'bird_on_it'
+```
+
+Run `bundle install`.
+
+## Usage
+
+### Model
+
+To decorate a model, first include _Bird On It_:
+
+```ruby
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  include BirdOnIt
+end
+```
+
+Then create a decorator either in `app/views/decorators` or `app/models` with the name matching your model and include `BirdOnIt::Decorator`.
+
+```ruby
+# app/decorators/post_decorator.rb
+class PostDecorator < ActiveRecord::Base
+  include BirdOnIt::Decorator
+
+  def display_title
+    object.title.humanize
+  end
+end
+```
+
+In the decorator, your decorated object is available via the `object` variable. If you prefer, you can also access it simply by calling methods to which your decorator does not respond:
+
+```ruby
+def display_title
+  title.humanize
+end
+```
+
+### Controller
+
+_Bird On It_ adds a `decorate` method you can call on your objects in your controller before they are passed to the view.
+
+```ruby
+# app/controllers/posts_controller.rb
+def show
+  @post = Post.find(params[:id]).decorate
+end
+```
+There is also a `decorate_collection` class method for decorating collections.
+
+```ruby
+# app/controllers/posts_controller.rb
+def index
+  @posts = Post.decorate_collection(Post.all)
+end
+```
+
+### View
+
+Use your decorated objects in the view as usual.
+
+```erb
+<div class="post">
+  <h1><%= @post.display_title %></h2>
+  <p><%= @post.body %></p>
+</div>
+```
+
+Some Rails helpers, such as the edit_path helper, do not work well with decorated objects. If you encounter one of these, you can work around this by passing the helper the decorated object, instead of the decorator. For example:
+
+```ruby
+<%= link_to 'Edit', edit_post_path(@post.object) %>
+```
+
+Other features, such as linking to the show page, or using the object with `form_for`, should continue to work as usual.
+
+```ruby
+<%= link_to 'Show', @post %>
+```
+
+```ruby
+<%= form_for(@post) do |f| %>
+  <%= f.text_field :material %>
+  <%= f.submit %>
+<% end %>
+```
+
+This project uses MIT-LICENSE.

data/lib/bird_on_it.rb

@@ -11,8 +11,7 @@ module BirdOnIt
 
   module ClassMethods
     def decorate_collection(collection)
-      collection = collection.to_a
-      collection.map { |item| decorator_class.new(item) }
+      Array(collection).map { |item| decorator_class.new(item) }
     end
 
     def decorator_class

data/lib/bird_on_it/decorator.rb

@@ -3,6 +3,8 @@ module BirdOnIt
     extend ActiveSupport::Concern
 
     included do
+      extend ActiveModel::Naming
+
       attr_accessor :object
 
       def initialize(object)

data/lib/bird_on_it/version.rb

@@ -1,3 +1,3 @@
 module BirdOnIt
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/bird_on_it_test.rb

@@ -1,56 +1,60 @@
 require 'test_helper'
 
 describe BirdOnIt do
-  class Decoratable
+  class ToteBag
     include BirdOnIt
 
-    def decoratable_instance_method
-      'hello from decoratable'
+    def color
+      'red'
     end
   end
 
-  class DecoratableDecorator
+  class ToteBagDecorator
     include BirdOnIt::Decorator
 
-    def decorator_method
-      'hello from decorator'
+    def color_description
+      if object.color
+        "This bag is #{color}"
+      else
+        "Unknown color"
+      end
     end
   end
 
-  let(:decoratable) { Decoratable.new }
-  let(:decorated)   { decoratable.decorate }
-
-  describe "when included" do
-    it "adds a class method #decorator_class that returns the decorator class" do
-      Decoratable.decorator_class.must_equal DecoratableDecorator
-    end
+  let(:tote_bag)           { ToteBag.new }
+  let(:tote_bag_decorator) { tote_bag.decorate }
 
+  describe "when BirdOnIt is included" do
     it "adds a method #decorate that returns a decorator" do
-      decoratable.decorate.class.must_equal DecoratableDecorator
+      tote_bag.decorate.class.must_equal ToteBagDecorator
     end
 
     it "adds a class method #decorate_collection that decorates a collection" do
-      collection = Decoratable.decorate_collection [Decoratable.new, Decoratable.new]
-      collection.map(&:class).must_equal [DecoratableDecorator, DecoratableDecorator]
+      collection = ToteBag.decorate_collection [ToteBag.new, ToteBag.new]
+      collection.map(&:class).must_equal [ToteBagDecorator, ToteBagDecorator]
+    end
+
+    it "adds a class method #decorator_class that returns the decorator class" do
+      ToteBag.decorator_class.must_equal ToteBagDecorator
     end
   end
 
-  describe DecoratableDecorator do
+  describe ToteBagDecorator do
     it "responds to its own instance methods" do
-      decorated.respond_to?(:decorator_method).must_equal true
-      decorated.decorator_method.must_equal 'hello from decorator'
+      tote_bag_decorator.respond_to?(:color_description).must_equal true
+      tote_bag_decorator.color_description.must_equal 'This bag is red'
     end
 
-    it "responds to the methods of the decorated object" do
-      decorated.respond_to?(:decoratable_instance_method).must_equal true
+    it "sends missing methods to its decorated object" do
+      tote_bag_decorator.color.must_equal 'red'
     end
 
-    it "sends missing methods to its decorated object" do
-      decorated.decoratable_instance_method.must_equal 'hello from decoratable'
+    it "responds to the methods of the decorated object" do
+      tote_bag_decorator.respond_to?(:color).must_equal true
     end
 
     it "has an object attribute that is the decorated object" do
-      decorated.object.must_equal decoratable
+      tote_bag_decorator.object.must_equal tote_bag
     end
   end
 end

data/test/dummy/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/test/dummy/app/controllers/tote_bags_controller.rb

@@ -0,0 +1,62 @@
+class ToteBagsController < ApplicationController
+  respond_to :html
+
+  # GET /tote_bags
+  def index
+    @tote_bags = ToteBag.decorate_collection(ToteBag.all)
+    respond_with @tote_bags
+  end
+
+  # GET /tote_bags/1
+  def show
+    @tote_bag = ToteBag.find(params[:id]).decorate
+    respond_with @tote_bag
+  end
+
+  # GET /tote_bags/new
+  def new
+    @tote_bag = ToteBag.new
+    respond_with @tote_bag
+  end
+
+  # GET /tote_bags/1/edit
+  def edit
+    @tote_bag = ToteBag.find(params[:id]).decorate
+    respond_with @tote_bag
+  end
+
+  # POST /tote_bags
+  def create
+    @tote_bag = ToteBag.new(tote_bag_params)
+
+    if @tote_bag.save
+      redirect_to @tote_bag, notice: 'Tote bag was successfully created.'
+    else
+      render :new
+    end
+  end
+
+  # PATCH/PUT /tote_bags/1
+  def update
+    @tote_bag = ToteBag.find(params[:id])
+
+    if @tote_bag.update(tote_bag_params)
+      redirect_to @tote_bag, notice: 'Tote bag was successfully updated.'
+    else
+      render :edit
+    end
+  end
+
+  # DELETE /tote_bags/1
+  def destroy
+    @tote_bag = ToteBag.find(params[:id])
+    @tote_bag.destroy
+    redirect_to tote_bags_url, notice: 'Tote bag was successfully destroyed.'
+  end
+
+  private
+
+  def tote_bag_params
+    params.require(:tote_bag).permit(:colour, :material, :straps)
+  end
+end

data/test/dummy/app/decorators/tote_bag_decorator.rb

@@ -0,0 +1,23 @@
+class ToteBagDecorator
+  include BirdOnIt::Decorator
+
+  def css_classes
+    css_classes = %w{tote-bag}
+
+    css_classes << 'straps' if object.straps?
+
+    css_classes.join(' ')
+  end
+
+  def colour_description
+    object.colour.present? ? object.colour : 'Has no colour'
+  end
+
+  def material_description
+    object.material.present? ? object.material : 'Unknown material'
+  end
+
+  def straps_description
+    object.straps? ? 'Has straps' : 'Strapless'
+  end
+end