draper 0.3.1 → 0.3.2

data/Readme.markdown

@@ -1,16 +1,59 @@
-Draper
-================
+## Heads Up!
 
-This gem makes it easy to apply the decorator pattern to the models in a Rails application.
+This gem is not yet production ready. The API is sure to change quickly and there could be side-effects I haven't discovered yet.
 
-## Why use decorators?
+Please only use it if you're playing around and helping me experiment! Thanks :)
 
-Helpers, as they're commonly used, are a bit odd. In both Ruby and Rails we approach everything from an Object-Oriented perspective, then with helpers we get procedural.
+# Draper
 
-The job of a helper is to take in data or a data object and output presentation-ready results. We can do that job in an OO fashion with a decorator.
+This gem makes it easy to apply the decorator pattern to the models in a Rails application. This gives you three wins:
+
+1. Replace most helpers with an object-oriented approach
+2. Filter data at the presentation level
+3. Enforce an interface between your controllers and view templates.
+
+## 1. Object Oriented Helpers
+
+Why hate helpers? In Ruby/Rails we approach everything from an Object-Oriented perspective, then with helpers we get procedural.The job of a helper is to take in data and output a presentation-ready string. We can do that job in an OO style with a decorator.
 
 In general, a decorator wraps an object with presentation-related accessor methods. For instance, if you had an `Article` object, then a decorator might add instance methods like `.formatted_published_at` or `.formatted_title` that output actual HTML.
 
+For example:
+
+```ruby
+class ArticleDecorator < Draper::Base
+  def formatted_published_at
+    date = content_tag(:span, published_at.strftime("%A, %B %e").squeeze(" "), :class => 'date')
+    time = content_tag(:span, published_at.strftime("%l:%M%p"), :class => 'time').delete(" ")
+    content_tag :span, date + time, :class => 'created_at'
+  end
+end
+```
+
+## 2. View-Layer Data Filtering
+
+Have you ever written a `to_xml` or `to_json` method in your model? Did it feel weird to put what is essentially view logic in your model?
+
+Or, in the course of formatting this data, did you wish you could access `current_user` down in the model? Maybe for guests your `to_json` is only going to show three attributes, but if the user is an admin they get to see them all.
+
+How would you handle this in the model layer? You'd probably pass the `current_user` or some role/flag down to `to_json`. That should still feel slimy.
+
+When you use a decorator you have the power of a Ruby object but it's a part of the view layer. This is where your `to_xml` belongs. It has access to the core data from the model, but it also knows about `current_user` because it can see the `ApplicationHelper` where that method is typically defined.
+
+For example:
+
+```ruby
+class ArticleDecorator < Draper::Base
+  ADMIN_VISIBLE_ATTRIBUTES = [:title, :body, :author, :status]
+  PUBLIC_VISIBLE_ATTRIBUTES = [:title, :body]
+
+  def to_xml
+    attr_set = current_user.admin? ? ADMIN_VISIBLE_ATTRIBUTES : PUBLIC_VISIBLE_ATTRIBUTES
+    self.subject.to_xml(:only => attr_set)
+  end
+end
+```
+
 ## How is it implemented?
 
 To implement the pattern in Rails we can:

data/lib/draper/base.rb

@@ -3,6 +3,7 @@ module Draper
     include ActionView::Helpers::TagHelper
     include ActionView::Helpers::UrlHelper
     include ActionView::Helpers::TextHelper
+    include ApplicationHelper #if defined?(ApplicationHelper)      
 
     require 'active_support/core_ext/class/attribute'
     class_attribute :denied, :allowed
@@ -10,6 +11,11 @@ module Draper
     
     DEFAULT_DENIED = Object.new.methods << :method_missing
     self.denied = DEFAULT_DENIED
+
+    def initialize(subject)
+      self.source = subject      
+      build_methods
+    end
     
     def self.denies(*input_denied)
       raise ArgumentError, "Specify at least one method (as a symbol) to exclude when using denies" if input_denied.empty?
@@ -19,15 +25,14 @@ module Draper
     
     def self.allows(*input_allows)
       raise ArgumentError, "Specify at least one method (as a symbol) to allow when using allows" if input_allows.empty?
-      #raise ArgumentError, "Use either 'allows' or 'denies', but not both." unless (self.denies == DEFAULT_EXCLUSIONS)
+      raise ArgumentError, "Use either 'allows' or 'denies', but not both." unless (self.denied == DEFAULT_DENIED)
       self.allowed = input_allows
     end
-    
-    def initialize(subject)
-      self.source = subject      
-      build_methods
-    end   
-    
+
+    def self.decorate(input)
+      input.respond_to?(:each) ? input.map{|i| new(i)} : new(input)
+    end
+        
   private
     def select_methods
       self.allowed || (source.public_methods - denied)
@@ -36,8 +41,8 @@ module Draper
     def build_methods
       select_methods.each do |method|
         (class << self; self; end).class_eval do
-          define_method method do |*args|
-            source.send method, *args
+          define_method method do |*args, &block|
+            source.send method, *args, &block
           end
         end
       end  

data/lib/draper/version.rb

@@ -1,3 +1,3 @@
 module Draper
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/spec/base_spec.rb

@@ -3,12 +3,31 @@ require 'draper'
 
 describe Draper::Base do
   subject{ Draper::Base.new(source) }
-  let(:source){ "Sample String" }
+  let(:source){ "Sample String" }    
     
   it "should return the wrapped object when asked for source" do
     subject.source.should == source
   end
   
+  it "should wrap source methods so they still accept blocks" do
+    subject.gsub("Sample"){|match| "Super"}.should == "Super String"
+  end
+  
+  context ".draper" do
+    it "should return a collection of wrapped objects when given a collection of source objects" do
+      sources = ["one", "two", "three"]
+      output = Draper::Base.decorate(sources)
+      output.should respond_to(:each)
+      output.size.should == sources.size
+      output.each{ |decorated| decorated.should be_instance_of(Draper::Base) }
+    end
+    
+    it "should return a single wrapped object when given a single source object" do
+      output = Draper::Base.decorate(source)
+      output.should be_instance_of(Draper::Base)
+    end
+  end
+  
   it "echos the methods of the wrapped class" do
     source.methods.each do |method|
       subject.should respond_to(method)
@@ -23,21 +42,6 @@ describe Draper::Base do
   
   describe "a sample usage with denies" do
     before(:all) do
-      class DecoratorWithDenies < Draper::Base  
-        denies :upcase
-        
-        def sample_content
-          content_tag :span, "Hello, World!"
-        end
-        
-        def sample_link
-          link_to "Hello", "/World"
-        end
-        
-        def sample_truncate
-          ActionView::Helpers::TextHelper.truncate("Once upon a time", :length => 7)
-        end
-      end
     end
     
     let(:subject_with_denies){ DecoratorWithDenies.new(source) }
@@ -69,12 +73,6 @@ describe Draper::Base do
   end
   
   describe "a sample usage with allows" do
-    before(:all) do
-      class DecoratorWithAllows < Draper::Base  
-        allows :upcase
-      end
-    end
-    
     let(:subject_with_allows){ DecoratorWithAllows.new(source) }
     
     it "should echo the allowed method" do
@@ -100,14 +98,14 @@ describe Draper::Base do
     }
     
     let(:using_allows_then_denies){
-      class DecoratorWithInvalidMixing < Draper::Base  
+      class DecoratorWithAllowsAndDenies < Draper::Base  
         allows :upcase
         denies :downcase
       end
     }    
     
     let(:using_denies_then_allows){
-      class DecoratorWithInvalidMixing < Draper::Base  
+      class DecoratorWithDeniesAndAllows < Draper::Base  
         denies :downcase
         allows :upcase        
       end
@@ -129,4 +127,11 @@ describe Draper::Base do
       expect {using_denies_then_allows}.should raise_error(ArgumentError)
     end
   end
+  
+  context "in a Rails application" do
+    it "should include ApplicationHelper if one exists" do
+      decorator = DecoratorApplicationHelper.decorate(Object.new)
+      decorator.uses_hello == "Hello, World!"
+    end
+  end
 end

data/spec/samples/application_helper.rb

@@ -0,0 +1,5 @@
+module ApplicationHelper
+  def hello
+    "Hello, World!"
+  end
+end

data/spec/samples/decorator_application_helper.rb

@@ -0,0 +1,5 @@
+class DecoratorApplicationHelper < Draper::Base  
+  def uses_hello
+    self.hello
+  end
+end

data/spec/samples/decorator_with_allows.rb

@@ -0,0 +1,3 @@
+class DecoratorWithAllows < Draper::Base  
+  allows :upcase
+end

data/spec/samples/decorator_with_denies.rb

@@ -0,0 +1,15 @@
+class DecoratorWithDenies < Draper::Base  
+  denies :upcase
+  
+  def sample_content
+    content_tag :span, "Hello, World!"
+  end
+  
+  def sample_link
+    link_to "Hello", "/World"
+  end
+  
+  def sample_truncate
+    ActionView::Helpers::TextHelper.truncate("Once upon a time", :length => 7)
+  end
+end

data/spec/spec_helper.rb

@@ -1,9 +1,12 @@
 require 'rubygems'
 require 'bundler'
+require './spec/samples/application_helper.rb'
 Bundler.require
+Dir.glob('./spec/samples/*') {|file| require file}
 require 'active_support'
 require 'action_view'
 require 'bundler/setup'
+
 require 'draper'
 
 Dir["spec/support/**/*.rb"].each do |file|

metadata

@@ -1,113 +1,116 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: draper
-version: !ruby/object:Gem::Version
-  version: 0.3.1
+version: !ruby/object:Gem::Version 
   prerelease: 
+  version: 0.3.2
 platform: ruby
-authors:
+authors: 
 - Jeff Casimir
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-30 00:00:00.000000000 -04:00
+
+date: 2011-07-10 00:00:00 -04:00
 default_executable: 
-dependencies:
-- !ruby/object:Gem::Dependency
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rake
-  requirement: &2154360120 !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - =
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
         version: 0.8.7
   type: :development
   prerelease: false
-  version_requirements: *2154360120
-- !ruby/object:Gem::Dependency
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
   name: rspec
-  requirement: &2154359620 !ruby/object:Gem::Requirement
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
         version: 2.0.1
   type: :development
   prerelease: false
-  version_requirements: *2154359620
-- !ruby/object:Gem::Dependency
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
   name: activesupport
-  requirement: &2154359160 !ruby/object:Gem::Requirement
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
         version: 3.0.9
   type: :development
   prerelease: false
-  version_requirements: *2154359160
-- !ruby/object:Gem::Dependency
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
   name: actionpack
-  requirement: &2154358700 !ruby/object:Gem::Requirement
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
         version: 3.0.9
   type: :development
   prerelease: false
-  version_requirements: *2154358700
-- !ruby/object:Gem::Dependency
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
   name: ruby-debug19
-  requirement: &2154358320 !ruby/object:Gem::Requirement
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
   prerelease: false
-  version_requirements: *2154358320
-- !ruby/object:Gem::Dependency
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
   name: guard
-  requirement: &2154357860 !ruby/object:Gem::Requirement
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
   prerelease: false
-  version_requirements: *2154357860
-- !ruby/object:Gem::Dependency
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
   name: guard-rspec
-  requirement: &2154381220 !ruby/object:Gem::Requirement
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
   prerelease: false
-  version_requirements: *2154381220
-- !ruby/object:Gem::Dependency
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
   name: rb-fsevent
-  requirement: &2154380800 !ruby/object:Gem::Requirement
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
   prerelease: false
-  version_requirements: *2154380800
-description: Draper reimagines the role of helpers in the view layer of a Rails application,
-  allowing an object-oriented approach rather than procedural.
-email:
+  version_requirements: *id008
+description: Draper reimagines the role of helpers in the view layer of a Rails application, allowing an object-oriented approach rather than procedural.
+email: 
 - jeff@casimircreative.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - Gemfile
 - Guardfile
@@ -121,38 +124,49 @@ files:
 - lib/generators/draper/model/model_generator.rb
 - lib/generators/draper/model/templates/model.rb
 - spec/base_spec.rb
+- spec/samples/application_helper.rb
+- spec/samples/decorator_application_helper.rb
+- spec/samples/decorator_with_allows.rb
+- spec/samples/decorator_with_denies.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/jcasimir/draper
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -258105380500550580
+      segments: 
       - 0
-      hash: 50059517492085377
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -258105380500550580
+      segments: 
       - 0
-      hash: 50059517492085377
+      version: "0"
 requirements: []
+
 rubyforge_project: draper
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Decorator pattern implmentation for Rails.
-test_files:
+test_files: 
 - spec/base_spec.rb
+- spec/samples/application_helper.rb
+- spec/samples/decorator_application_helper.rb
+- spec/samples/decorator_with_allows.rb
+- spec/samples/decorator_with_denies.rb
 - spec/spec_helper.rb