draper 0.18.0 → 1.1.0

data/Rakefile

@@ -1,47 +1,69 @@
-require 'bundler/gem_tasks'
 require 'rake'
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-RCOV = RUBY_VERSION.to_f == 1.8
+def run_in_dummy_app(command)
+  success = system("cd spec/dummy && #{command}")
+  raise "#{command} failed" unless success
+end
+
+task "default" => "ci"
+
+desc "Run all tests for CI"
+task "ci" => "spec"
 
-namespace :spec do
+desc "Run all specs"
+task "spec" => "spec:all"
 
-  RSpec::Core::RakeTask.new(:coverage) do |t|
-    t.pattern = 'spec/**/*_spec.rb'
+namespace "spec" do
+  task "all" => ["draper", "generators", "integration"]
 
-    if RCOV
-      t.rcov = true
-      t.rcov_opts = '--exclude osx\/objc,spec,gems\/'
+  def spec_task(name)
+    desc "Run #{name} specs"
+    RSpec::Core::RakeTask.new(name) do |t|
+      t.pattern = "spec/#{name}/**/*_spec.rb"
     end
   end
 
-  RSpec::Core::RakeTask.new(:normal) do |t|
-    t.pattern ='spec/**/*_spec.rb'
-    t.rcov = false
-  end
+  spec_task "draper"
+  spec_task "generators"
 
-  namespace :coverage do
-    desc "Cleanup coverage data"
-    task :cleanup do
-      rm_rf 'coverage.data'
-      rm_rf 'coverage'
-    end
+  desc "Run integration specs"
+  task "integration" => ["db:setup", "integration:all"]
 
-    desc "Browse the code coverage report."
-    task :report => ["spec:coverage:cleanup", "spec:coverage"] do
-      if RCOV
-        require "launchy"
-        Launchy.open("coverage/index.html")
-      else
-        require 'cover_me'
-        CoverMe.complete!
+  namespace "integration" do
+    task "all" => ["development", "production", "test"]
+
+    ["development", "production"].each do |environment|
+      task environment do
+        Rake::Task["spec:integration:run"].execute environment
       end
     end
-  end
 
-end
+    task "run" do |t, environment|
+      puts "Running integration specs in #{environment}"
+
+      ENV["RAILS_ENV"] = environment
+      success = system("rspec spec/integration")
 
-desc "RSpec tests"
-task "spec" => "spec:normal"
+      raise "Integration specs failed in #{environment}" unless success
+    end
 
-task "default" => "spec"
+    task "test" do
+      puts "Running rake in dummy app"
+      ENV["RAILS_ENV"] = "test"
+      run_in_dummy_app "rake"
+    end
+  end
+end
+
+namespace "db" do
+  desc "Set up databases for integration testing"
+  task "setup" do
+    puts "Setting up databases"
+    run_in_dummy_app "rm -f db/*.sqlite3"
+    run_in_dummy_app "RAILS_ENV=development rake db:schema:load db:seed"
+    run_in_dummy_app "RAILS_ENV=production rake db:schema:load db:seed"
+    run_in_dummy_app "RAILS_ENV=test rake db:schema:load"
+  end
+end

data/draper.gemspec

@@ -7,22 +7,24 @@ Gem::Specification.new do |s|
   s.version     = Draper::VERSION
   s.authors     = ["Jeff Casimir", "Steve Klabnik"]
   s.email       = ["jeff@casimircreative.com", "steve@steveklabnik.com"]
-  s.homepage    = "http://github.com/jcasimir/draper"
-  s.summary     = "Decorator pattern implementation for Rails."
-  s.description = "Draper implements a decorator or presenter pattern for Rails applications."
+  s.homepage    = "http://github.com/drapergem/draper"
+  s.summary     = "View Models for Rails"
+  s.description = "Draper adds an object-oriented layer of presentation logic to your Rails apps."
   s.rubyforge_project = "draper"
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_dependency 'activesupport', '~> 3.2'
-  s.add_dependency 'actionpack', '~> 3.2'
+  s.add_dependency 'activesupport', '>= 3.0'
+  s.add_dependency 'actionpack', '>= 3.0'
+  s.add_dependency 'request_store', '~> 1.0.3'
 
   s.add_development_dependency 'ammeter'
-  s.add_development_dependency 'rake', '~> 0.9.2'
-  s.add_development_dependency 'rspec', '~> 2.10'
-  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rake', '>= 0.9.2'
+  s.add_development_dependency 'rspec', '~> 2.12'
+  s.add_development_dependency 'rspec-mocks', '>= 2.12.1'
+  s.add_development_dependency 'rspec-rails', '~> 2.12'
   s.add_development_dependency 'minitest-rails', '~> 0.2'
-  s.add_development_dependency 'minitest', '~> 3.0' if RUBY_PLATFORM == "java"
+  s.add_development_dependency 'capybara'
 end

data/lib/draper/automatic_delegation.rb

@@ -0,0 +1,50 @@
+module Draper
+  module AutomaticDelegation
+    extend ActiveSupport::Concern
+
+    # Delegates missing instance methods to the source object.
+    def method_missing(method, *args, &block)
+      return super unless delegatable?(method)
+
+      self.class.delegate method
+      send(method, *args, &block)
+    end
+
+    # Checks if the decorator responds to an instance method, or is able to
+    # proxy it to the source object.
+    def respond_to?(method, include_private = false)
+      super || delegatable?(method)
+    end
+
+    # @private
+    def delegatable?(method)
+      source.respond_to?(method)
+    end
+
+    module ClassMethods
+      # Proxies missing class methods to the source class.
+      def method_missing(method, *args, &block)
+        return super unless delegatable?(method)
+
+        source_class.send(method, *args, &block)
+      end
+
+      # Checks if the decorator responds to a class method, or is able to proxy
+      # it to the source class.
+      def respond_to?(method, include_private = false)
+        super || delegatable?(method)
+      end
+
+      # @private
+      def delegatable?(method)
+        source_class? && source_class.respond_to?(method)
+      end
+    end
+
+    included do
+      private :delegatable?
+      private_class_method :delegatable?
+    end
+
+  end
+end

data/lib/draper/collection_decorator.rb

@@ -0,0 +1,107 @@
+module Draper
+  class CollectionDecorator
+    include Enumerable
+    include Draper::ViewHelpers
+    extend Draper::Delegation
+
+    # @return [Hash] extra data to be used in user-defined methods, and passed
+    #   to each item's decorator.
+    attr_accessor :context
+
+    array_methods = Array.instance_methods - Object.instance_methods
+    delegate :==, :as_json, *array_methods, to: :decorated_collection
+
+    # @param [Enumerable] source
+    #   collection to decorate.
+    # @option options [Class, nil] :with (nil)
+    #   the decorator class used to decorate each item. When `nil`, it is
+    #   inferred from the collection decorator class if possible (e.g.
+    #   `ProductsDecorator` maps to `ProductDecorator`), otherwise each item's
+    #   {Decoratable#decorate decorate} method will be used.
+    # @option options [Hash] :context ({})
+    #   extra data to be stored in the collection decorator and used in
+    #   user-defined methods, and passed to each item's decorator.
+    def initialize(source, options = {})
+      options.assert_valid_keys(:with, :context)
+      @source = source
+      @decorator_class = options[:with]
+      @context = options.fetch(:context, {})
+    end
+
+    class << self
+      alias_method :decorate, :new
+    end
+
+    # @return [Array] the decorated items.
+    def decorated_collection
+      @decorated_collection ||= source.map{|item| decorate_item(item)}
+    end
+
+    # Delegated to the decorated collection when using the block form
+    # (`Enumerable#find`) or to the decorator class if not
+    # (`ActiveRecord::FinderMethods#find`)
+    def find(*args, &block)
+      if block_given?
+        decorated_collection.find(*args, &block)
+      else
+        decorator_class.find(*args)
+      end
+    end
+
+    def to_s
+      klass = begin
+        decorator_class
+      rescue Draper::UninferrableDecoratorError
+        "inferred decorators"
+      end
+
+      "#<#{self.class.name} of #{klass} for #{source.inspect}>"
+    end
+
+    def context=(value)
+      @context = value
+      each {|item| item.context = value } if @decorated_collection
+    end
+
+    # @return [Class] the decorator class used to decorate each item, as set by
+    #   {#initialize} or as inferred from the collection decorator class (e.g.
+    #   `ProductsDecorator` maps to `ProductDecorator`).
+    def decorator_class
+      @decorator_class ||= self.class.inferred_decorator_class
+    end
+
+    protected
+
+    # @return the collection being decorated.
+    attr_reader :source
+
+    # Decorates the given item.
+    def decorate_item(item)
+      item_decorator.call(item, context: context)
+    end
+
+    private
+
+    def self.inferred_decorator_class
+      decorator_name = "#{name.chomp("Decorator").singularize}Decorator"
+      decorator_uninferrable if decorator_name == name
+
+      decorator_name.constantize
+
+    rescue NameError
+      decorator_uninferrable
+    end
+
+    def self.decorator_uninferrable
+      raise Draper::UninferrableDecoratorError.new(self)
+    end
+
+    def item_decorator
+      @item_decorator ||= begin
+        decorator_class.method(:decorate)
+      rescue Draper::UninferrableDecoratorError
+        ->(item, options) { item.decorate(options) }
+      end
+    end
+  end
+end

data/lib/draper/decoratable/equality.rb

@@ -0,0 +1,14 @@
+module Draper
+  module Decoratable
+    module Equality
+      # Compares self with a possibly-decorated object.
+      #
+      # @return [Boolean]
+      def ==(other)
+        super ||
+          other.respond_to?(:decorated?) && other.decorated? &&
+          other.respond_to?(:source) && self == other.source
+      end
+    end
+  end
+end

data/lib/draper/decoratable.rb

@@ -0,0 +1,79 @@
+require 'draper/decoratable/equality'
+
+module Draper
+  # Provides shortcuts to decorate objects directly, so you can do
+  # `@product.decorate` instead of `ProductDecorator.new(@product)`.
+  #
+  # This module is included by default into `ActiveRecord::Base` and
+  # `Mongoid::Document`, but you're using another ORM, or want to decorate
+  # plain old Ruby objects, you can include it manually.
+  module Decoratable
+    extend ActiveSupport::Concern
+    include Draper::Decoratable::Equality
+
+    # Decorates the object using the inferred {#decorator_class}.
+    # @param [Hash] options
+    #   see {Decorator#initialize}
+    def decorate(options = {})
+      decorator_class.decorate(self, options)
+    end
+
+    # (see ClassMethods#decorator_class)
+    def decorator_class
+      self.class.decorator_class
+    end
+
+    # The list of decorators that have been applied to the object.
+    #
+    # @return [Array<Class>] `[]`
+    def applied_decorators
+      []
+    end
+
+    # (see Decorator#decorated_with?)
+    # @return [false]
+    def decorated_with?(decorator_class)
+      false
+    end
+
+    # Checks if this object is decorated.
+    #
+    # @return [false]
+    def decorated?
+      false
+    end
+
+    module ClassMethods
+
+      # Decorates a collection of objects. Used at the end of a scope chain.
+      #
+      # @example
+      #   Product.popular.decorate
+      # @param [Hash] options
+      #   see {Decorator.decorate_collection}.
+      def decorate(options = {})
+        decorator_class.decorate_collection(self.scoped, options)
+      end
+
+      # Infers the decorator class to be used by {Decoratable#decorate} (e.g.
+      # `Product` maps to `ProductDecorator`).
+      #
+      # @return [Class] the inferred decorator class.
+      def decorator_class
+        prefix = respond_to?(:model_name) ? model_name : name
+        "#{prefix}Decorator".constantize
+      rescue NameError
+        raise Draper::UninferrableDecoratorError.new(self)
+      end
+
+      # Compares with possibly-decorated objects.
+      #
+      # @return [Boolean]
+      def ===(other)
+        super || (other.respond_to?(:source) && super(other.source))
+      end
+
+    end
+
+  end
+end

data/lib/draper/decorated_association.rb

@@ -0,0 +1,74 @@
+module Draper
+  # @private
+  class DecoratedAssociation
+
+    def initialize(owner, association, options)
+      options.assert_valid_keys(:with, :scope, :context)
+
+      @owner = owner
+      @association = association
+
+      @decorator_class = options[:with]
+      @scope = options[:scope]
+      @context = options.fetch(:context, owner.context)
+    end
+
+    def call
+      return undecorated if undecorated.nil?
+      decorated
+    end
+
+    def context
+      return @context.call(owner.context) if @context.respond_to?(:call)
+      @context
+    end
+
+    private
+
+    attr_reader :owner, :association, :scope
+
+    def source
+      owner.source
+    end
+
+    def undecorated
+      @undecorated ||= begin
+        associated = source.send(association)
+        associated = associated.send(scope) if scope
+        associated
+      end
+    end
+
+    def decorated
+      @decorated ||= decorator.call(undecorated, context: context)
+    end
+
+    def collection?
+      undecorated.respond_to?(:first)
+    end
+
+    def decorator
+      return collection_decorator if collection?
+      decorator_class.method(:decorate)
+    end
+
+    def collection_decorator
+      klass = decorator_class || Draper::CollectionDecorator
+
+      if klass.respond_to?(:decorate_collection)
+        klass.method(:decorate_collection)
+      else
+        klass.method(:decorate)
+      end
+    end
+
+    def decorator_class
+      @decorator_class || inferred_decorator_class
+    end
+
+    def inferred_decorator_class
+      undecorated.decorator_class if undecorated.respond_to?(:decorator_class)
+    end
+
+  end
+end

data/lib/draper/decorator.rb

@@ -0,0 +1,235 @@
+module Draper
+  class Decorator
+    include Draper::ViewHelpers
+    extend Draper::Delegation
+    include ActiveModel::Serialization
+
+    # @return the object being decorated.
+    attr_reader :source
+    alias_method :model, :source
+    alias_method :to_source, :source
+
+    # @return [Hash] extra data to be used in user-defined methods.
+    attr_accessor :context
+
+    # Wraps an object in a new instance of the decorator.
+    #
+    # Decorators may be applied to other decorators. However, applying a
+    # decorator to an instance of itself will create a decorator with the same
+    # source as the original, rather than redecorating the other instance.
+    #
+    # @param [Object] source
+    #   object to decorate.
+    # @option options [Hash] :context ({})
+    #   extra data to be stored in the decorator and used in user-defined
+    #   methods.
+    def initialize(source, options = {})
+      options.assert_valid_keys(:context)
+      @source = source
+      @context = options.fetch(:context, {})
+      handle_multiple_decoration(options) if source.instance_of?(self.class)
+    end
+
+    class << self
+      alias_method :decorate, :new
+    end
+
+    # Automatically delegates instance methods to the source object. Class
+    # methods will be delegated to the {source_class}, if it is set.
+    #
+    # @return [void]
+    def self.delegate_all
+      include Draper::AutomaticDelegation
+    end
+
+    # Sets the source class corresponding to the decorator class.
+    #
+    # @note This is only necessary if you wish to proxy class methods to the
+    #   source (including when using {decorates_finders}), and the source class
+    #   cannot be inferred from the decorator class (e.g. `ProductDecorator`
+    #   maps to `Product`).
+    # @param [String, Symbol, Class] source_class
+    #   source class (or class name) that corresponds to this decorator.
+    # @return [void]
+    def self.decorates(source_class)
+      @source_class = source_class.to_s.camelize.constantize
+    end
+
+    # Returns the source class corresponding to the decorator class, as set by
+    # {decorates}, or as inferred from the decorator class name (e.g.
+    # `ProductDecorator` maps to `Product`).
+    #
+    # @return [Class] the source class that corresponds to this decorator.
+    def self.source_class
+      @source_class ||= inferred_source_class
+    end
+
+    # Checks whether this decorator class has a corresponding {source_class}.
+    def self.source_class?
+      source_class
+    rescue Draper::UninferrableSourceError
+      false
+    end
+
+    # Automatically decorates ActiveRecord finder methods, so that you can use
+    # `ProductDecorator.find(id)` instead of
+    # `ProductDecorator.decorate(Product.find(id))`.
+    #
+    # Finder methods are applied to the {source_class}.
+    #
+    # @return [void]
+    def self.decorates_finders
+      extend Draper::Finders
+    end
+
+    # Automatically decorate an association.
+    #
+    # @param [Symbol] association
+    #   name of the association to decorate (e.g. `:products`).
+    # @option options [Class] :with
+    #   the decorator to apply to the association.
+    # @option options [Symbol] :scope
+    #   a scope to apply when fetching the association.
+    # @option options [Hash, #call] :context
+    #   extra data to be stored in the associated decorator. If omitted, the
+    #   associated decorator's context will be the same as the parent
+    #   decorator's. If a Proc is given, it will be called with the parent's
+    #   context and should return a new context hash for the association.
+    # @return [void]
+    def self.decorates_association(association, options = {})
+      options.assert_valid_keys(:with, :scope, :context)
+      define_method(association) do
+        decorated_associations[association] ||= Draper::DecoratedAssociation.new(self, association, options)
+        decorated_associations[association].call
+      end
+    end
+
+    # @overload decorates_associations(*associations, options = {})
+    #   Automatically decorate multiple associations.
+    #   @param [Symbols*] associations
+    #     names of the associations to decorate.
+    #   @param [Hash] options
+    #     see {decorates_association}.
+    #   @return [void]
+    def self.decorates_associations(*associations)
+      options = associations.extract_options!
+      associations.each do |association|
+        decorates_association(association, options)
+      end
+    end
+
+    # Decorates a collection of objects. The class of the collection decorator
+    # is inferred from the decorator class if possible (e.g. `ProductDecorator`
+    # maps to `ProductsDecorator`), but otherwise defaults to
+    # {Draper::CollectionDecorator}.
+    #
+    # @param [Object] source
+    #   collection to decorate.
+    # @option options [Class, nil] :with (self)
+    #   the decorator class used to decorate each item. When `nil`, it is
+    #   inferred from each item.
+    # @option options [Hash] :context
+    #   extra data to be stored in the collection decorator.
+    def self.decorate_collection(source, options = {})
+      options.assert_valid_keys(:with, :context)
+      collection_decorator_class.new(source, options.reverse_merge(with: self))
+    end
+
+    # @return [Array<Class>] the list of decorators that have been applied to
+    #   the object.
+    def applied_decorators
+      chain = source.respond_to?(:applied_decorators) ? source.applied_decorators : []
+      chain << self.class
+    end
+
+    # Checks if a given decorator has been applied to the object.
+    #
+    # @param [Class] decorator_class
+    def decorated_with?(decorator_class)
+      applied_decorators.include?(decorator_class)
+    end
+
+    # Checks if this object is decorated.
+    #
+    # @return [true]
+    def decorated?
+      true
+    end
+
+    # Compares the source with a possibly-decorated object.
+    #
+    # @return [Boolean]
+    def ==(other)
+      source.extend(Draper::Decoratable::Equality) == other
+    end
+
+    # Checks if `self.kind_of?(klass)` or `source.kind_of?(klass)`
+    #
+    # @param [Class] klass
+    def kind_of?(klass)
+      super || source.kind_of?(klass)
+    end
+    alias_method :is_a?, :kind_of?
+
+    # Checks if `self.instance_of?(klass)` or `source.instance_of?(klass)`
+    #
+    # @param [Class] klass
+    def instance_of?(klass)
+      super || source.instance_of?(klass)
+    end
+
+    # In case source is nil
+    delegate :present?
+
+    # ActiveModel compatibility
+    # @private
+    def to_model
+      self
+    end
+
+    # ActiveModel compatibility
+    delegate :attributes, :to_param, :to_partial_path
+
+    # ActiveModel compatibility
+    singleton_class.delegate :model_name, to: :source_class
+
+    # @return [Class] the class created by {decorate_collection}.
+    def self.collection_decorator_class
+      collection_decorator_name.constantize
+    rescue NameError
+      Draper::CollectionDecorator
+    end
+
+    private
+
+    def self.source_name
+      raise NameError if name.nil? || name.demodulize !~ /.+Decorator$/
+      name.chomp("Decorator")
+    end
+
+    def self.inferred_source_class
+      source_name.constantize
+    rescue NameError
+      raise Draper::UninferrableSourceError.new(self)
+    end
+
+    def self.collection_decorator_name
+      plural = source_name.pluralize
+      raise NameError if plural == source_name
+      "#{plural}Decorator"
+    end
+
+    def handle_multiple_decoration(options)
+      if source.applied_decorators.last == self.class
+        @context = source.context unless options.has_key?(:context)
+        @source = source.source
+      else
+        warn "Reapplying #{self.class} decorator to target that is already decorated with it. Call stack:\n#{caller(1).join("\n")}"
+      end
+    end
+
+    def decorated_associations
+      @decorated_associations ||= {}
+    end
+  end
+end