draper 1.0.0.beta6 → 1.0.0

data/lib/draper/decorated_association.rb

@@ -1,4 +1,5 @@
 module Draper
+  # @private
   class DecoratedAssociation
 
     def initialize(owner, association, options)
@@ -24,7 +25,7 @@ module Draper
 
     private
 
-    attr_reader :owner, :association, :decorator_class, :scope
+    attr_reader :owner, :association, :scope
 
     def source
       owner.source
@@ -48,12 +49,7 @@ module Draper
 
     def decorator
       return collection_decorator if collection?
-
-      if decorator_class
-        decorator_class.method(:decorate)
-      else
-        ->(item, options) { item.decorate(options) }
-      end
+      decorator_class.method(:decorate)
     end
 
     def collection_decorator
@@ -66,5 +62,13 @@ module Draper
       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

@@ -3,83 +3,102 @@ 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
 
-    # Initialize a new decorator instance by passing in
-    # an instance of the source class. Pass in an optional
-    # :context inside the options hash which is available
-    # for later use.
+    # Wraps an object in a new instance of the decorator.
     #
-    # A decorator cannot be applied to other instances of the
-    # same decorator and will instead result in a decorator
-    # with the same target as the original.
-    # You can, however, apply several decorators in a chain but
-    # you will get a warning if the same decorator appears at
-    # multiple places in the chain.
+    # 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 context available to the decorator
+    # @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.is_a?(Draper::Decorator)
+      handle_multiple_decoration(options) if source.instance_of?(self.class)
     end
 
     class << self
       alias_method :decorate, :new
     end
 
-    # Specify the class that this class decorates.
+    # Automatically delegates instance methods to the source object. Class
+    # methods will be delegated to the {source_class}, if it is set.
     #
-    # @param [String, Symbol, Class] Class or name of class to decorate.
-    def self.decorates(klass)
-      @source_class = klass.to_s.camelize.constantize
+    # @return [void]
+    def self.delegate_all
+      include Draper::AutomaticDelegation
     end
 
-    # @return [Class] The source class corresponding to this
-    #   decorator class
+    # 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
+    # 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
+    # Automatically decorates ActiveRecord finder methods, so that you can use
+    # `ProductDecorator.find(id)` instead of
     # `ProductDecorator.decorate(Product.find(id))`.
     #
-    # The model class to be found is defined by `decorates` or
-    # inferred from the decorator class name.
+    # Finder methods are applied to the {source_class}.
     #
+    # @return [void]
     def self.decorates_finders
       extend Draper::Finders
     end
 
-    # Typically called within a decorator definition, this method causes
-    # the assocation to be decorated when it is retrieved.
-    #
-    # @param [Symbol] association name of association to decorate, like `: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 context available to decorated
-    #   objects in collection.  Passing a `lambda` or similar will result in that
-    #   block being called when the association is evaluated.  The block will be
-    #   passed the base decorator's `context` Hash and should return the desired
-    #   context Hash for the decorated items.
+    # 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
@@ -88,11 +107,13 @@ module Draper
       end
     end
 
-    # A convenience method for decorating multiple associations. Calls
-    # decorates_association on each of the given symbols.
-    #
-    # @param [Symbols*] associations names of associations to decorate
-    # @param [Hash] options passed to `decorate_association`
+    # @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|
@@ -100,167 +121,112 @@ module Draper
       end
     end
 
-    # Specifies a black list of methods which may *not* be proxied to
-    # the wrapped object.
-    #
-    # Do not use both `.allows` and `.denies` together, either write
-    # a whitelist with `.allows` or a blacklist with `.denies`
-    #
-    # @param [Symbols*] methods methods to deny like `:find, :find_by_name`
-    def self.denies(*methods)
-      security.denies(*methods)
-    end
-
-    # Specifies that all methods may *not* be proxied to the wrapped object.
-    #
-    # Do not use `.allows` and `.denies` in combination with '.denies_all'
-    def self.denies_all
-      security.denies_all
-    end
-
-    # Specifies a white list of methods which *may* be proxied to
-    # the wrapped object. When `allows` is used, only the listed
-    # methods and methods defined in the decorator itself will be
-    # available.
-    #
-    # Do not use both `.allows` and `.denies` together, either write
-    # a whitelist with `.allows` or a blacklist with `.denies`
-    #
-    # @param [Symbols*] methods methods to allow like `:find, :find_by_name`
-    def self.allows(*methods)
-      security.allows(*methods)
-    end
-
-    # Creates a new CollectionDecorator for the given collection.
+    # 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
-    # @param [Hash] options passed to each item's decorator (except
-    #   for the keys listed below)
-    # @option options [Class] :with (self) the class used to decorate
-    #   items
-    # @option options [Hash] :context context available to decorated items
+    # @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)
-      Draper::CollectionDecorator.new(source, options.reverse_merge(with: self))
+      collection_decorator_class.new(source, options.reverse_merge(with: self))
     end
 
-    # Get the chain of decorators applied to the object.
-    #
-    # @return [Array] list of decorator classes
+    # @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.
+    # 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
 
-    # Delegates == to the decorated models
+    # Delegated to the source object.
     #
-    # @return [Boolean] true if other's model == self's model
+    # @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?
 
-    # We always want to delegate present, in case we decorate a nil object.
+    # Checks if `self.instance_of?(klass)` or `source.instance_of?(klass)`
     #
-    # I don't like the idea of decorating a nil object, but we'll deal with
-    # that later.
-    def present?
-      source.present?
+    # @param [Class] klass
+    def instance_of?(klass)
+      super || source.instance_of?(klass)
     end
 
-    # For ActiveModel compatibilty
+    # In case source is nil
+    delegate :present?
+
+    # ActiveModel compatibility
+    # @private
     def to_model
       self
     end
 
-    # For ActiveModel compatibility
-    def to_param
-      source.to_param
-    end
+    # ActiveModel compatibility
+    delegate :to_param, :to_partial_path
 
-    def method_missing(method, *args, &block)
-      if delegatable_method?(method)
-        self.class.define_proxy(method)
-        send(method, *args, &block)
-      else
-        super
-      end
-    end
+    # ActiveModel compatibility
+    singleton_class.delegate :model_name, to: :source_class
 
-    def respond_to?(method, include_private = false)
-      super || delegatable_method?(method)
-    end
-
-    def self.method_missing(method, *args, &block)
-      if delegatable_method?(method)
-        source_class.send(method, *args, &block)
-      else
-        super
-      end
-    end
-
-    def self.respond_to?(method, include_private = false)
-      super || delegatable_method?(method)
+    # @return [Class] the class created by {decorate_collection}.
+    def self.collection_decorator_class
+      collection_decorator_name.constantize
+    rescue NameError
+      Draper::CollectionDecorator
     end
 
     private
 
-    def delegatable_method?(method)
-      allow?(method) && source.respond_to?(method)
-    end
-
-    def self.delegatable_method?(method)
-      source_class? && source_class.respond_to?(method)
+    def self.source_name
+      raise NameError if name.nil? || name.demodulize !~ /.+Decorator$/
+      name.chomp("Decorator")
     end
 
     def self.inferred_source_class
-      uninferrable_source if name.nil? || name.demodulize !~ /.+Decorator$/
-
-      begin
-        name.chomp("Decorator").constantize
-      rescue NameError
-        uninferrable_source
-      end
-    end
-
-    def self.uninferrable_source
+      source_name.constantize
+    rescue NameError
       raise Draper::UninferrableSourceError.new(self)
     end
 
-    def self.define_proxy(method)
-      define_method(method) do |*args, &block|
-        source.send(method, *args, &block)
-      end
-    end
-
-    def self.security
-      @security ||= Security.new
-    end
-
-    def allow?(method)
-      self.class.security.allow?(method)
+    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.instance_of?(self.class)
+      if source.applied_decorators.last == self.class
         @context = source.context unless options.has_key?(:context)
         @source = source.source
-      elsif source.decorated_with?(self.class)
+      else
         warn "Reapplying #{self.class} decorator to target that is already decorated with it. Call stack:\n#{caller(1).join("\n")}"
       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

@@ -1,4 +1,7 @@
 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 = {})
@@ -17,17 +20,17 @@ module Draper
       decorate(source_class.last, options)
     end
 
+    # Decorates dynamic finder methods (`find_all_by_` and friends).
     def method_missing(method, *args, &block)
-      result = super
+      return super unless method =~ /^find_(all_|last_|or_(initialize_|create_))?by_/
+
+      result = source_class.send(method, *args, &block)
       options = args.extract_options!
 
-      case method.to_s
-      when /^find_((last_)?by_|or_(initialize|create)_by_)/
-        decorate(result, options)
-      when /^find_all_by_/
+      if method =~ /^find_all/
         decorate_collection(result, options)
       else
-        result
+        decorate(result, options)
       end
     end
   end