draper 1.2.0 → 1.2.1

data/lib/draper/automatic_delegation.rb

@@ -18,7 +18,7 @@ module Draper
 
     # @private
     def delegatable?(method)
-      source.respond_to?(method)
+      object.respond_to?(method)
     end
 
     module ClassMethods
@@ -26,7 +26,7 @@ module Draper
       def method_missing(method, *args, &block)
         return super unless delegatable?(method)
 
-        source_class.send(method, *args, &block)
+        object_class.send(method, *args, &block)
       end
 
       # Checks if the decorator responds to a class method, or is able to proxy
@@ -37,7 +37,7 @@ module Draper
 
       # @private
       def delegatable?(method)
-        source_class? && source_class.respond_to?(method)
+        object_class? && object_class.respond_to?(method)
       end
 
       # @private

data/lib/draper/collection_decorator.rb

@@ -15,19 +15,17 @@ module Draper
     array_methods = Array.instance_methods - Object.instance_methods
     delegate :==, :as_json, *array_methods, to: :decorated_collection
 
-    # @param [Enumerable] source
+    # @param [Enumerable] object
     #   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
+    #   the decorator class used to decorate each item. When `nil`, 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 = {})
+    def initialize(object, options = {})
       options.assert_valid_keys(:with, :context)
-      @source = source
+      @object = object
       @decorator_class = options[:with]
       @context = options.fetch(:context, {})
     end
@@ -38,7 +36,7 @@ module Draper
 
     # @return [Array] the decorated items.
     def decorated_collection
-      @decorated_collection ||= source.map{|item| decorate_item(item)}
+      @decorated_collection ||= object.map{|item| decorate_item(item)}
     end
 
     # Delegated to the decorated collection when using the block form
@@ -48,12 +46,13 @@ module Draper
       if block_given?
         decorated_collection.find(*args, &block)
       else
-        decorator_class.find(*args)
+        ActiveSupport::Deprecation.warn("Using ActiveRecord's `find` on a CollectionDecorator is deprecated. Call `find` on a model, and then decorate the result", caller)
+        decorate_item(object.find(*args))
       end
     end
 
     def to_s
-      "#<#{self.class.name} of #{decorator_class || "inferred decorators"} for #{source.inspect}>"
+      "#<#{self.class.name} of #{decorator_class || "inferred decorators"} for #{object.inspect}>"
     end
 
     def context=(value)
@@ -73,10 +72,15 @@ module Draper
     end
     alias_method :is_a?, :kind_of?
 
+    def replace(other)
+      decorated_collection.replace(other)
+      self
+    end
+
     protected
 
     # @return the collection being decorated.
-    attr_reader :source
+    attr_reader :object
 
     # Decorates the given item.
     def decorate_item(item)

data/lib/draper/decoratable.rb

@@ -73,7 +73,7 @@ module Draper
       #
       # @return [Boolean]
       def ===(other)
-        super || (other.respond_to?(:source) && super(other.source))
+        super || (other.respond_to?(:object) && super(other.object))
       end
 
     end

data/lib/draper/decoratable/equality.rb

@@ -19,7 +19,7 @@ module Draper
       # @private
       def self.test_for_decorator(object, other)
         other.respond_to?(:decorated?) && other.decorated? &&
-        other.respond_to?(:source) && test(object, other.source)
+        other.respond_to?(:object) && test(object, other.object)
       end
     end
   end

data/lib/draper/decorated_association.rb

@@ -25,7 +25,7 @@ module Draper
     attr_reader :factory, :owner, :association, :scope
 
     def decorate
-      associated = owner.source.send(association)
+      associated = owner.object.send(association)
       associated = associated.send(scope) if scope
 
       @decorated = factory.decorate(associated, context_args: owner.context)

data/lib/draper/decorator.rb

@@ -8,9 +8,10 @@ module Draper
     include ActiveModel::Serializers::Xml
 
     # @return the object being decorated.
-    attr_reader :source
-    alias_method :model, :source
-    alias_method :to_source, :source
+    attr_reader :object
+    alias_method :model, :object
+    alias_method :source, :object # TODO: deprecate this
+    alias_method :to_source, :object # TODO: deprecate this
 
     # @return [Hash] extra data to be used in user-defined methods.
     attr_accessor :context
@@ -21,16 +22,16 @@ module Draper
     # 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
+    # @param [Object] object
     #   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 = {})
+    def initialize(object, options = {})
       options.assert_valid_keys(:context)
-      @source = source
+      @object = object
       @context = options.fetch(:context, {})
-      handle_multiple_decoration(options) if source.instance_of?(self.class)
+      handle_multiple_decoration(options) if object.instance_of?(self.class)
     end
 
     class << self
@@ -38,7 +39,7 @@ module Draper
     end
 
     # Automatically delegates instance methods to the source object. Class
-    # methods will be delegated to the {source_class}, if it is set.
+    # methods will be delegated to the {object_class}, if it is set.
     #
     # @return [void]
     def self.delegate_all
@@ -51,11 +52,11 @@ module Draper
     #   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
+    # @param [String, Symbol, Class] object_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
+    def self.decorates(object_class)
+      @object_class = object_class.to_s.camelize.constantize
     end
 
     # Returns the source class corresponding to the decorator class, as set by
@@ -63,22 +64,27 @@ module Draper
     # `ProductDecorator` maps to `Product`).
     #
     # @return [Class] the source class that corresponds to this decorator.
-    def self.source_class
-      @source_class ||= inferred_source_class
+    def self.object_class
+      @object_class ||= inferred_object_class
     end
 
-    # Checks whether this decorator class has a corresponding {source_class}.
-    def self.source_class?
-      source_class
+    # Checks whether this decorator class has a corresponding {object_class}.
+    def self.object_class?
+      object_class
     rescue Draper::UninferrableSourceError
       false
     end
 
+    class << self # TODO deprecate this
+      alias_method :source_class, :object_class
+      alias_method :source_class?, :object_class?
+    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}.
+    # Finder methods are applied to the {object_class}.
     #
     # @return [void]
     def self.decorates_finders
@@ -126,22 +132,22 @@ module Draper
     # maps to `ProductsDecorator`), but otherwise defaults to
     # {Draper::CollectionDecorator}.
     #
-    # @param [Object] source
+    # @param [Object] object
     #   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 = {})
+    def self.decorate_collection(object, options = {})
       options.assert_valid_keys(:with, :context)
-      collection_decorator_class.new(source, options.reverse_merge(with: self))
+      collection_decorator_class.new(object, 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 = object.respond_to?(:applied_decorators) ? object.applied_decorators : []
       chain << self.class
     end
 
@@ -159,30 +165,30 @@ module Draper
       true
     end
 
-    # Compares the source with a possibly-decorated object.
+    # Compares the source object with a possibly-decorated object.
     #
     # @return [Boolean]
     def ==(other)
-      Draper::Decoratable::Equality.test(source, other)
+      Draper::Decoratable::Equality.test(object, other)
     end
 
-    # Checks if `self.kind_of?(klass)` or `source.kind_of?(klass)`
+    # Checks if `self.kind_of?(klass)` or `object.kind_of?(klass)`
     #
     # @param [Class] klass
     def kind_of?(klass)
-      super || source.kind_of?(klass)
+      super || object.kind_of?(klass)
     end
     alias_method :is_a?, :kind_of?
 
-    # Checks if `self.instance_of?(klass)` or `source.instance_of?(klass)`
+    # Checks if `self.instance_of?(klass)` or `object.instance_of?(klass)`
     #
     # @param [Class] klass
     def instance_of?(klass)
-      super || source.instance_of?(klass)
+      super || object.instance_of?(klass)
     end
 
-    # In case source is nil
-    delegate :present?
+    # In case object is nil
+    delegate :present?, :blank?
 
     # ActiveModel compatibility
     # @private
@@ -190,17 +196,17 @@ module Draper
       self
     end
 
-    # @return [Hash] the source's attributes, sliced to only include those
+    # @return [Hash] the object's attributes, sliced to only include those
     # implemented by the decorator.
     def attributes
-      source.attributes.select {|attribute, _| respond_to?(attribute) }
+      object.attributes.select {|attribute, _| respond_to?(attribute) }
     end
 
     # ActiveModel compatibility
     delegate :to_param, :to_partial_path
 
     # ActiveModel compatibility
-    singleton_class.delegate :model_name, to: :source_class
+    singleton_class.delegate :model_name, to: :object_class
 
     # @return [Class] the class created by {decorate_collection}.
     def self.collection_decorator_class
@@ -213,13 +219,13 @@ module Draper
 
     private
 
-    def self.source_name
+    def self.object_class_name
       raise NameError if name.nil? || name.demodulize !~ /.+Decorator$/
       name.chomp("Decorator")
     end
 
-    def self.inferred_source_class
-      name = source_name
+    def self.inferred_object_class
+      name = object_class_name
       name.constantize
     rescue NameError => error
       raise if name && !error.missing_name?(name)
@@ -227,15 +233,15 @@ module Draper
     end
 
     def self.collection_decorator_name
-      plural = source_name.pluralize
-      raise NameError if plural == source_name
+      plural = object_class_name.pluralize
+      raise NameError if plural == object_class_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
+      if object.applied_decorators.last == self.class
+        @context = object.context unless options.has_key?(:context)
+        @object = object.object
       else
         warn "Reapplying #{self.class} decorator to target that is already decorated with it. Call stack:\n#{caller(1).join("\n")}"
       end

data/lib/draper/delegation.rb

@@ -2,12 +2,12 @@ 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.
+    #   to make `:object` the default delegation target.
     #
     #   @return [void]
     def delegate(*methods)
       options = methods.extract_options!
-      super *methods, options.reverse_merge(to: :source)
+      super *methods, options.reverse_merge(to: :object)
     end
   end
 end

data/lib/draper/factory.rb

@@ -18,7 +18,7 @@ module Draper
     # Decorates an object, inferring whether to create a singular or collection
     # decorator from the type of object passed.
     #
-    # @param [Object] source
+    # @param [Object] object
     #   object to decorate.
     # @option options [Hash] context
     #   extra data to be stored in the decorator. Overrides any context passed
@@ -26,9 +26,9 @@ module Draper
     # @option options [Object, Array] context_args (nil)
     #   argument(s) to be passed to the context proc.
     # @return [Decorator, CollectionDecorator] the decorated object.
-    def decorate(source, options = {})
-      return nil if source.nil?
-      Worker.new(decorator_class, source).call(options.reverse_merge(default_options))
+    def decorate(object, options = {})
+      return nil if object.nil?
+      Worker.new(decorator_class, object).call(options.reverse_merge(default_options))
     end
 
     private
@@ -37,29 +37,33 @@ module Draper
 
     # @private
     class Worker
-      def initialize(decorator_class, source)
+      def initialize(decorator_class, object)
         @decorator_class = decorator_class
-        @source = source
+        @object = object
       end
 
       def call(options)
         update_context options
-        decorator.call(source, options)
+        decorator.call(object, options)
       end
 
       def decorator
         return decorator_method(decorator_class) if decorator_class
-        return source_decorator if decoratable?
+        return object_decorator if decoratable?
         return decorator_method(Draper::CollectionDecorator) if collection?
-        raise Draper::UninferrableDecoratorError.new(source.class)
+        raise Draper::UninferrableDecoratorError.new(object.class)
       end
 
       private
 
-      attr_reader :decorator_class, :source
+      attr_reader :decorator_class, :object
 
-      def source_decorator
-        ->(source, options) { source.decorate(options) }
+      def object_decorator
+        if collection?
+          ->(object, options) { object.decorator_class.decorate_collection(object, options.reverse_merge(with: nil))}
+        else
+          ->(object, options) { object.decorate(options) }
+        end
       end
 
       def decorator_method(klass)
@@ -71,11 +75,11 @@ module Draper
       end
 
       def collection?
-        source.respond_to?(:first)
+        object.respond_to?(:first)
       end
 
       def decoratable?
-        source.respond_to?(:decorate)
+        object.respond_to?(:decorate)
       end
 
       def update_context(options)

data/lib/draper/finders.rb

@@ -5,26 +5,26 @@ module Draper
   module Finders
 
     def find(id, options = {})
-      decorate(source_class.find(id), options)
+      decorate(object_class.find(id), options)
     end
 
     def all(options = {})
-      decorate_collection(source_class.all, options)
+      decorate_collection(object_class.all, options)
     end
 
     def first(options = {})
-      decorate(source_class.first, options)
+      decorate(object_class.first, options)
     end
 
     def last(options = {})
-      decorate(source_class.last, options)
+      decorate(object_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)
+      result = object_class.send(method, *args, &block)
       options = args.extract_options!
 
       if method =~ /^find_all/