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' require 'active_support/descendants_tracker' 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. # instantiate_observers 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 # => [#] 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 # update, 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 # # => [#] 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 custom_notification, passing as arguments # the current object and :foo. 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 # count_observers 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 Comment#save 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 CommentObserver will be tied to observing Comment, # ProductManagerObserver to ProductManager, and so on. If # you want to name your observer differently than the class you're interested # in observing, you can use the Observer.observe class method which # takes either the concrete class (Product) or a symbol for that # class (:product): # # 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 AuditObserver will now act on both updates to Account # and Balance 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