require 'singleton'
require 'active_model/observer_array'
require 'active_support/core_ext/module/aliasing'
require 'active_support/core_ext/module/remove_method'
require 'active_support/core_ext/string/inflections'
require 'active_support/core_ext/enumerable'
require 'active_support/core_ext/object/try'
module ActiveModel
# == Active \Model Observers Activation
module Observing
extend ActiveSupport::Concern
included do
extend ActiveSupport::DescendantsTracker
end
module ClassMethods
# Activates the observers assigned.
#
# class ORM
# include ActiveModel::Observing
# end
#
# # Calls PersonObserver.instance
# ORM.observers = :person_observer
#
# # Calls Cacher.instance and GarbageCollector.instance
# ORM.observers = :cacher, :garbage_collector
#
# # Same as above, just using explicit class references
# ORM.observers = Cacher, GarbageCollector
#
# Note: Setting this does not instantiate the observers yet.
# <tt>instantiate_observers</tt> is called during startup, and before
# each development request.
def observers=(*values)
observers.replace(values.flatten)
end
# Gets an array of observers observing this model. The array also provides
# +enable+ and +disable+ methods that allow you to selectively enable and
# disable observers (see ActiveModel::ObserverArray.enable and
# ActiveModel::ObserverArray.disable for more on this).
#
# class ORM
# include ActiveModel::Observing
# end
#
# ORM.observers = :cacher, :garbage_collector
# ORM.observers # => [:cacher, :garbage_collector]
# ORM.observers.class # => ActiveModel::ObserverArray
def observers
@observers ||= ObserverArray.new(self)
end
# Returns the current observer instances.
#
# class Foo
# include ActiveModel::Observing
#
# attr_accessor :status
# end
#
# class FooObserver < ActiveModel::Observer
# def on_spec(record, *args)
# record.status = true
# end
# end
#
# Foo.observers = FooObserver
# Foo.instantiate_observers
#
# Foo.observer_instances # => [#<FooObserver:0x007fc212c40820>]
def observer_instances
@observer_instances ||= []
end
# Instantiate the global observers.
#
# class Foo
# include ActiveModel::Observing
#
# attr_accessor :status
# end
#
# class FooObserver < ActiveModel::Observer
# def on_spec(record, *args)
# record.status = true
# end
# end
#
# Foo.observers = FooObserver
#
# foo = Foo.new
# foo.status = false
# foo.notify_observers(:on_spec)
# foo.status # => false
#
# Foo.instantiate_observers # => [FooObserver]
#
# foo = Foo.new
# foo.status = false
# foo.notify_observers(:on_spec)
# foo.status # => true
def instantiate_observers
observers.each { |o| instantiate_observer(o) }
end
# Add a new observer to the pool. The new observer needs to respond to
# <tt>update</tt>, otherwise it raises an +ArgumentError+ exception.
#
# class Foo
# include ActiveModel::Observing
# end
#
# class FooObserver < ActiveModel::Observer
# end
#
# Foo.add_observer(FooObserver.instance)
#
# Foo.observers_instance
# # => [#<FooObserver:0x007fccf55d9390>]
def add_observer(observer)
unless observer.respond_to? :update
raise ArgumentError, "observer needs to respond to 'update'"
end
observer_instances << observer
end
# Fires notifications to model's observers.
#
# def save
# notify_observers(:before_save)
# ...
# notify_observers(:after_save)
# end
#
# Custom notifications can be sent in a similar fashion:
#
# notify_observers(:custom_notification, :foo)
#
# This will call <tt>custom_notification</tt>, passing as arguments
# the current object and <tt>:foo</tt>.
def notify_observers(*args)
observer_instances.each { |observer| observer.update(*args) }
end
# Returns the total number of instantiated observers.
#
# class Foo
# include ActiveModel::Observing
#
# attr_accessor :status
# end
#
# class FooObserver < ActiveModel::Observer
# def on_spec(record, *args)
# record.status = true
# end
# end
#
# Foo.observers = FooObserver
# Foo.observers_count # => 0
# Foo.instantiate_observers
# Foo.observers_count # => 1
def observers_count
observer_instances.size
end
# <tt>count_observers</tt> is deprecated. Use #observers_count.
def count_observers
msg = "count_observers is deprecated in favor of observers_count"
ActiveSupport::Deprecation.warn msg
observers_count
end
protected
def instantiate_observer(observer) #:nodoc:
# string/symbol
if observer.respond_to?(:to_sym)
observer = observer.to_s.camelize.constantize
end
if observer.respond_to?(:instance)
observer.instance
else
raise ArgumentError,
"#{observer} must be a lowercase, underscored class name (or " +
"the class itself) responding to the method :instance. " +
"Example: Person.observers = :big_brother # calls " +
"BigBrother.instance"
end
end
# Notify observers when the observed class is subclassed.
def inherited(subclass) #:nodoc:
super
notify_observers :observed_class_inherited, subclass
end
end
# Notify a change to the list of observers.
#
# class Foo
# include ActiveModel::Observing
#
# attr_accessor :status
# end
#
# class FooObserver < ActiveModel::Observer
# def on_spec(record, *args)
# record.status = true
# end
# end
#
# Foo.observers = FooObserver
# Foo.instantiate_observers # => [FooObserver]
#
# foo = Foo.new
# foo.status = false
# foo.notify_observers(:on_spec)
# foo.status # => true
#
# See ActiveModel::Observing::ClassMethods.notify_observers for more
# information.
def notify_observers(method, *extra_args)
self.class.notify_observers(method, self, *extra_args)
end
end
# == Active \Model Observers
#
# Observer classes respond to life cycle callbacks to implement trigger-like
# behavior outside the original class. This is a great way to reduce the
# clutter that normally comes when the model class is burdened with
# functionality that doesn't pertain to the core responsibility of the
# class.
#
# class CommentObserver < ActiveModel::Observer
# def after_save(comment)
# Notifications.comment('admin@do.com', 'New comment was posted', comment).deliver
# end
# end
#
# This Observer sends an email when a <tt>Comment#save</tt> is finished.
#
# class ContactObserver < ActiveModel::Observer
# def after_create(contact)
# contact.logger.info('New contact added!')
# end
#
# def after_destroy(contact)
# contact.logger.warn("Contact with an id of #{contact.id} was destroyed!")
# end
# end
#
# This Observer uses logger to log when specific callbacks are triggered.
#
# == \Observing a class that can't be inferred
#
# Observers will by default be mapped to the class with which they share a
# name. So <tt>CommentObserver</tt> will be tied to observing <tt>Comment</tt>,
# <tt>ProductManagerObserver</tt> to <tt>ProductManager</tt>, and so on. If
# you want to name your observer differently than the class you're interested
# in observing, you can use the <tt>Observer.observe</tt> class method which
# takes either the concrete class (<tt>Product</tt>) or a symbol for that
# class (<tt>:product</tt>):
#
# class AuditObserver < ActiveModel::Observer
# observe :account
#
# def after_update(account)
# AuditTrail.new(account, 'UPDATED')
# end
# end
#
# If the audit observer needs to watch more than one kind of object, this can
# be specified with multiple arguments:
#
# class AuditObserver < ActiveModel::Observer
# observe :account, :balance
#
# def after_update(record)
# AuditTrail.new(record, 'UPDATED')
# end
# end
#
# The <tt>AuditObserver</tt> will now act on both updates to <tt>Account</tt>
# and <tt>Balance</tt> by treating them both as records.
#
# If you're using an Observer in a Rails application with Active Record, be
# sure to read about the necessary configuration in the documentation for
# ActiveRecord::Observer.
class Observer
include Singleton
extend ActiveSupport::DescendantsTracker
class << self
# Attaches the observer to the supplied model classes.
#
# class AuditObserver < ActiveModel::Observer
# observe :account, :balance
# end
#
# AuditObserver.observed_classes # => [Account, Balance]
def observe(*models)
models.flatten!
models.collect! { |model| model.respond_to?(:to_sym) ? model.to_s.camelize.constantize : model }
singleton_class.redefine_method(:observed_classes) { models }
end
# Returns an array of Classes to observe.
#
# AccountObserver.observed_classes # => [Account]
#
# You can override this instead of using the +observe+ helper.
#
# class AuditObserver < ActiveModel::Observer
# def self.observed_classes
# [Account, Balance]
# end
# end
def observed_classes
Array(observed_class)
end
# Returns the class observed by default. It's inferred from the observer's
# class name.
#
# PersonObserver.observed_class # => Person
# AccountObserver.observed_class # => Account
def observed_class
name[/(.*)Observer/, 1].try :constantize
end
end
# Start observing the declared classes and their subclasses.
# Called automatically by the instance method.
def initialize #:nodoc:
observed_classes.each { |klass| add_observer!(klass) }
end
def observed_classes #:nodoc:
self.class.observed_classes
end
# Send observed_method(object) if the method exists and
# the observer is enabled for the given object's class.
def update(observed_method, object, *extra_args, &block) #:nodoc:
return if !respond_to?(observed_method) || disabled_for?(object)
send(observed_method, object, *extra_args, &block)
end
# Special method sent by the observed class when it is inherited.
# Passes the new subclass.
def observed_class_inherited(subclass) #:nodoc:
self.class.observe(observed_classes + [subclass])
add_observer!(subclass)
end
protected
def add_observer!(klass) #:nodoc:
klass.add_observer(self)
end
# Returns true if notifications are disabled for this object.
def disabled_for?(object) #:nodoc:
klass = object.class
return false unless klass.respond_to?(:observers)
klass.observers.disabled_for?(self)
end
end
end