draper 0.18.0 → 1.0.0

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 a nicely-separated 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.rb

@@ -0,0 +1,83 @@
+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
+
+    # 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
+
+    # Compares with possibly-decorated objects.
+    #
+    # @return [Boolean]
+    def ==(other)
+      super || (other.respond_to?(:source) && self == other.source)
+    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,238 @@
+require 'active_support/core_ext/array/extract_options'
+
+module Draper
+  class Decorator
+    include Draper::ViewHelpers
+    extend Draper::Delegation
+    include ActiveModel::Serialization if defined?(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.to_a if source.respond_to?(:to_a) # forces evaluation of a lazy query from AR
+      @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
+
+    # Delegated to the source object.
+    #
+    # @return [Boolean]
+    def ==(other)
+      source == (other.respond_to?(:source) ? other.source : 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 :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

data/lib/draper/delegation.rb

@@ -0,0 +1,13 @@
+module Draper
+  module Delegation
+    # @overload delegate(*methods, options = {})
+    #   Overrides {http://api.rubyonrails.org/classes/Module.html#method-i-delegate Module.delegate}
+    #   to make `:source` the default delegation target.
+    #
+    #   @return [void]
+    def delegate(*methods)
+      options = methods.extract_options!
+      super *methods, options.reverse_merge(to: :source)
+    end
+  end
+end

data/lib/draper/finders.rb

@@ -0,0 +1,37 @@
+module Draper
+  # Provides automatically-decorated finder methods for your decorators. You
+  # do not have to extend this module directly; it is extended by
+  # {Decorator.decorates_finders}.
+  module Finders
+
+    def find(id, options = {})
+      decorate(source_class.find(id), options)
+    end
+
+    def all(options = {})
+      decorate_collection(source_class.all, options)
+    end
+
+    def first(options = {})
+      decorate(source_class.first, options)
+    end
+
+    def last(options = {})
+      decorate(source_class.last, options)
+    end
+
+    # Decorates dynamic finder methods (`find_all_by_` and friends).
+    def method_missing(method, *args, &block)
+      return super unless method =~ /^find_(all_|last_|or_(initialize_|create_))?by_/
+
+      result = source_class.send(method, *args, &block)
+      options = args.extract_options!
+
+      if method =~ /^find_all/
+        decorate_collection(result, options)
+      else
+        decorate(result, options)
+      end
+    end
+  end
+end

data/lib/draper/helper_proxy.rb

@@ -0,0 +1,17 @@
+module Draper
+  # Provides access to helper methods - both Rails built-in helpers, and those
+  # defined in your application.
+  class HelperProxy
+
+    # Sends helper methods to the view context.
+    def method_missing(method, *args, &block)
+      view_context.send(method, *args, &block)
+    end
+
+    private
+
+    def view_context
+      Draper::ViewContext.current
+    end
+  end
+end

data/lib/draper/lazy_helpers.rb

@@ -1,11 +1,15 @@
 module Draper
+  # Include this module in your decorators to get direct access to the helpers
+  # so that you can stop typing `h.` everywhere, at the cost of mixing in a
+  # bazillion methods.
   module LazyHelpers
-    def method_missing(method_name, *args, &block)
-      begin
-        helpers.send method_name, *args, &block
-      rescue NoMethodError
-        super
-      end
+
+    # Sends missing methods to the {HelperProxy}.
+    def method_missing(method, *args, &block)
+      helpers.send(method, *args, &block)
+    rescue NoMethodError
+      super
     end
+
   end
 end