lib/draper/decorator.rb
require 'draper/compatibility/global_id'
module Draper
class Decorator
include Draper::ViewHelpers
include Draper::Compatibility::GlobalID if defined?(GlobalID)
extend Draper::Delegation
include ActiveModel::Serialization
include ActiveModel::Serializers::JSON
include ActiveModel::Serializers::Xml
# @return the object being decorated.
attr_reader :object
alias :model :object
# @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] object
# object to decorate.
# @option options [Hash] :context ({})
# extra data to be stored in the decorator and used in user-defined
# methods.
def initialize(object, options = {})
options.assert_valid_keys(:context)
@object = object
@context = options.fetch(:context, {})
handle_multiple_decoration(options) if object.instance_of?(self.class)
end
class << self
alias :decorate :new
end
# Automatically delegates instance methods to the source object. Class
# methods will be delegated to the {object_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] object_class
# source class (or class name) that corresponds to this decorator.
# @return [void]
def self.decorates(object_class)
@object_class = object_class.to_s.camelize.constantize
alias_object_to_object_class_name
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.object_class
@object_class ||= inferred_object_class
end
# Checks whether this decorator class has a corresponding {object_class}.
def self.object_class?
object_class
rescue Draper::UninferrableObjectError
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 {object_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] 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(object, options = {})
options.assert_valid_keys(:with, :context)
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 = object.respond_to?(:applied_decorators) ? object.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 object with a possibly-decorated object.
#
# @return [Boolean]
def ==(other)
Draper::Decoratable::Equality.test(object, other)
end
# Delegates equality to :== as expected
#
# @return [Boolean]
def eql?(other)
self == other
end
# Returns a unique hash for a decorated object based on
# the decorator class and the object being decorated.
#
# @return [Fixnum]
def hash
self.class.hash ^ object.hash
end
# Checks if `self.kind_of?(klass)` or `object.kind_of?(klass)`
#
# @param [Class] klass
def kind_of?(klass)
super || object.kind_of?(klass)
end
alias :is_a? :kind_of?
# Checks if `self.instance_of?(klass)` or `object.instance_of?(klass)`
#
# @param [Class] klass
def instance_of?(klass)
super || object.instance_of?(klass)
end
delegate :to_s
# In case object is nil
delegate :present?, :blank?
# ActiveModel compatibility
# @private
def to_model
self
end
# @return [Hash] the object's attributes, sliced to only include those
# implemented by the decorator.
def attributes
object.attributes.select {|attribute, _| respond_to?(attribute) }
end
# ActiveModel compatibility
delegate :to_param, :to_partial_path
# ActiveModel compatibility
singleton_class.delegate :model_name, to: :object_class
# @return [Class] the class created by {decorate_collection}.
def self.collection_decorator_class
name = collection_decorator_name
name_constant = name&.safe_constantize
name_constant || Draper::CollectionDecorator
end
private
def self.inherited(subclass)
subclass.alias_object_to_object_class_name
super
end
def self.alias_object_to_object_class_name
alias_method object_class.name.underscore, :object if object_class?
end
def self.object_class_name
return nil if name.nil? || name.demodulize !~ /.+Decorator$/
name.chomp("Decorator")
end
def self.inferred_object_class
name = object_class_name
name_constant = name&.safe_constantize
return name_constant unless name_constant.nil?
raise Draper::UninferrableObjectError.new(self)
end
def self.collection_decorator_name
singular = object_class_name
plural = singular&.pluralize
"#{plural}Decorator" unless plural == singular
end
def handle_multiple_decoration(options)
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
end
def decorated_associations
@decorated_associations ||= {}
end
end
end