jamesgolick-draper 1.1.1a

data/lib/draper/decorates_assigned.rb

@@ -0,0 +1,44 @@
+module Draper
+  module DecoratesAssigned
+    # @overload decorates_assigned(*variables, options = {})
+    #   Defines a helper method to access decorated instance variables.
+    #
+    #   @example
+    #     # app/controllers/articles_controller.rb
+    #     class ArticlesController < ApplicationController
+    #       decorates_assigned :article
+    #
+    #       def show
+    #         @article = Article.find(params[:id])
+    #       end
+    #     end
+    #
+    #     # app/views/articles/show.html.erb
+    #     <%= article.decorated_title %>
+    #
+    #   @param [Symbols*] variables
+    #     names of the instance variables to decorate (without the `@`).
+    #   @param [Hash] options
+    #   @option options [Decorator, CollectionDecorator] :with (nil)
+    #     decorator class to use. If nil, it is inferred from the instance
+    #     variable.
+    #   @option options [Hash, #call] :context
+    #     extra data to be stored in the decorator. If a Proc is given, it will
+    #     be passed the controller and should return a new context hash.
+    def decorates_assigned(*variables)
+      factory = Draper::Factory.new(variables.extract_options!)
+
+      variables.each do |variable|
+        undecorated = "@#{variable}"
+        decorated = "@decorated_#{variable}"
+
+        define_method variable do
+          return instance_variable_get(decorated) if instance_variable_defined?(decorated)
+          instance_variable_set decorated, factory.decorate(instance_variable_get(undecorated), context_args: self)
+        end
+
+        helper_method variable
+      end
+    end
+  end
+end

data/lib/draper/decorator.rb

@@ -0,0 +1,248 @@
+module Draper
+  class Decorator
+    include Draper::ViewHelpers
+    extend Draper::Delegation
+
+    include ActiveModel::Serialization
+    include ActiveModel::Serializers::JSON
+    include ActiveModel::Serializers::Xml
+
+    # @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)
+      Draper::Decoratable::Equality.test(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
+
+    # @return [Hash] the source's attributes, sliced to only include those
+    # implemented by the decorator.
+    def attributes
+      source.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
+
+    # @return [Class] the class created by {decorate_collection}.
+    def self.collection_decorator_class
+      name = collection_decorator_name
+      name.constantize
+    rescue NameError => error
+      raise if name && !error.missing_name?(name)
+      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
+      name = source_name
+      name.constantize
+    rescue NameError => error
+      raise if name && !error.missing_name?(name)
+      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/factory.rb

@@ -0,0 +1,87 @@
+module Draper
+  class Factory
+    # Creates a decorator factory.
+    #
+    # @option options [Decorator, CollectionDecorator] :with (nil)
+    #   decorator class to use. If nil, it is inferred from the object
+    #   passed to {#decorate}.
+    # @option options [Hash, #call] context
+    #   extra data to be stored in created decorators. If a proc is given, it
+    #   will be called each time {#decorate} is called and its return value
+    #   will be used as the context.
+    def initialize(options = {})
+      options.assert_valid_keys(:with, :context)
+      @decorator_class = options.delete(:with)
+      @default_options = options
+    end
+
+    # Decorates an object, inferring whether to create a singular or collection
+    # decorator from the type of object passed.
+    #
+    # @param [Object] source
+    #   object to decorate.
+    # @option options [Hash] context
+    #   extra data to be stored in the decorator. Overrides any context passed
+    #   to the constructor.
+    # @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))
+    end
+
+    private
+
+    attr_reader :decorator_class, :default_options
+
+    # @private
+    class Worker
+      def initialize(decorator_class, source)
+        @decorator_class = decorator_class
+        @source = source
+      end
+
+      def call(options)
+        update_context options
+        decorator.call(source, options)
+      end
+
+      def decorator
+        return decorator_method(decorator_class) if decorator_class
+        return source_decorator if decoratable?
+        return decorator_method(Draper::CollectionDecorator) if collection?
+        raise Draper::UninferrableDecoratorError.new(source.class)
+      end
+
+      private
+
+      attr_reader :decorator_class, :source
+
+      def source_decorator
+        ->(source, options) { source.decorate(options) }
+      end
+
+      def decorator_method(klass)
+        if collection? && klass.respond_to?(:decorate_collection)
+          klass.method(:decorate_collection)
+        else
+          klass.method(:decorate)
+        end
+      end
+
+      def collection?
+        source.respond_to?(:first)
+      end
+
+      def decoratable?
+        source.respond_to?(:decorate)
+      end
+
+      def update_context(options)
+        args = options.delete(:context_args)
+        options[:context] = options[:context].call(*Array.wrap(args)) if options[:context].respond_to?(:call)
+      end
+    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,38 @@
+module Draper
+  # Provides access to helper methods - both Rails built-in helpers, and those
+  # defined in your application.
+  class HelperProxy
+
+    # @overload initialize(view_context)
+    def initialize(view_context = nil)
+      view_context ||= current_view_context # backwards compatibility
+
+      @view_context = view_context
+    end
+
+    # Sends helper methods to the view context.
+    def method_missing(method, *args, &block)
+      self.class.define_proxy method
+      send(method, *args, &block)
+    end
+
+    delegate :capture, to: :view_context
+
+    protected
+
+    attr_reader :view_context
+
+    private
+
+    def self.define_proxy(name)
+      define_method name do |*args, &block|
+        view_context.send(name, *args, &block)
+      end
+    end
+
+    def current_view_context
+      ActiveSupport::Deprecation.warn("wrong number of arguments (0 for 1) passed to Draper::HelperProxy.new", caller[1..-1])
+      Draper::ViewContext.current.view_context
+    end
+  end
+end