diff options
Diffstat (limited to 'activemodel/lib/active_model/observing.rb')
| -rw-r--r-- | activemodel/lib/active_model/observing.rb | 260 |
1 files changed, 191 insertions, 69 deletions
diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index cd8eb357de..9db7639ea3 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -1,13 +1,14 @@ require 'singleton' require 'active_model/observer_array' -require 'active_support/core_ext/array/wrap' 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 @@ -16,9 +17,7 @@ module ActiveModel end module ClassMethods - # == Active Model Observers Activation - # - # Activates the observers assigned. Examples: + # Activates the observers assigned. # # class ORM # include ActiveModel::Observing @@ -34,85 +33,200 @@ module ActiveModel # ORM.observers = Cacher, GarbageCollector # # Note: Setting this does not instantiate the observers yet. - # +instantiate_observers+ is called during startup, and before + # <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 <tt>ActiveModel::ObserverArray.enable</tt> and - # <tt>ActiveModel::ObserverArray.disable</tt> for more on this) + # 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 - # Gets the current observer instances. + # 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 'update', otherwise it - # raises an +ArgumentError+ exception. + # 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'" + raise ArgumentError, "observer needs to respond to 'update'" end observer_instances << observer end - # Notify list of observers of a change. - def notify_observers(*arg) - observer_instances.each { |observer| observer.update(*arg) } + # 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 - # Total number of observers. - def count_observers + # 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.to_s.camelize.constantize.instance - elsif observer.respond_to?(:instance) + 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 an " + - "instance of the class itself) responding to the instance " + - "method. Example: Person.observers = :big_brother # calls " + + "#{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) + def inherited(subclass) #:nodoc: super notify_observers :observed_class_inherited, subclass end end - private - # Fires notifications to model's observers - # - # def save - # notify_observers(:before_save) - # ... - # notify_observers(:after_save) - # end - def notify_observers(method) - self.class.notify_observers(method, self) - 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 @@ -121,15 +235,15 @@ module ActiveModel # 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. Example: + # class. # # class CommentObserver < ActiveModel::Observer # def after_save(comment) - # Notifications.comment("admin@do.com", "New comment was posted", comment).deliver + # Notifications.comment('admin@do.com', 'New comment was posted', comment).deliver # end # end # - # This Observer sends an email when a Comment#save is finished. + # This Observer sends an email when a <tt>Comment#save</tt> is finished. # # class ContactObserver < ActiveModel::Observer # def after_create(contact) @@ -146,52 +260,60 @@ module ActiveModel # == 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 <tt>Observer.observe</tt> - # class method which takes either the concrete class (Product) or a symbol for that - # class (:product): + # 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") + # 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: + # 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") + # AuditTrail.new(record, 'UPDATED') # end # end # - # The AuditObserver will now act on both updates to Account and Balance by treating - # them both as records. + # 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 + # 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 } - redefine_method(:observed_classes) { models } + 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 @@ -200,22 +322,22 @@ module ActiveModel # end # end def observed_classes - Array.wrap(observed_class) + Array(observed_class) end - # The class observed by default is inferred from the observer's class name: - # assert_equal Person, PersonObserver.observed_class + # 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 - if observed_class_name = name[/(.*)Observer/, 1] - observed_class_name.constantize - else - nil - end + name[/(.*)Observer/, 1].try :constantize end end # Start observing the declared classes and their subclasses. - def initialize + # Called automatically by the instance method. + def initialize #:nodoc: observed_classes.each { |klass| add_observer!(klass) } end @@ -225,10 +347,9 @@ module ActiveModel # Send observed_method(object) if the method exists and # the observer is enabled for the given object's class. - def update(observed_method, object, &block) #:nodoc: - return unless respond_to?(observed_method) - return if disabled_for?(object) - send(observed_method, object, &block) + 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. @@ -243,7 +364,8 @@ module ActiveModel klass.add_observer(self) end - def disabled_for?(object) + # 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) |