Permalink
Browse files

Merge pull request #418 from myronmarston/am_observer_doc_updates

Add documentation for new observer enable/disable feature.
  • Loading branch information...
2 parents 9c2c25c + 99363dc commit dd752a5de97d95bf1098e1ef461ff5fcde4d7ee5 @tenderlove tenderlove committed May 6, 2011
@@ -15,6 +15,8 @@
* ActiveModel::AttributeMethods allows attributes to be defined on demand [Alexander Uvarov]
+* Add support for selectively enabling/disabling observers [Myron Marston]
+
*Rails 3.0.2 (unreleased)*
@@ -2,22 +2,65 @@
module ActiveModel
# Stores the enabled/disabled state of individual observers for
- # a particular model classes.
+ # a particular model class.
class ObserverArray < Array
attr_reader :model_class
def initialize(model_class, *args)
@model_class = model_class
super(*args)
end
+ # Returns true if the given observer is disabled for the model class.
def disabled_for?(observer)
disabled_observers.include?(observer.class)
end
+ # Disables one or more observers. This supports multiple forms:
+ #
+ # ORM.observers.disable :user_observer
+ # # => disables the UserObserver
+ #
+ # User.observers.disable AuditTrail
+ # # => disables the AuditTrail observer for User notifications.
+ # # Other models will still notify the AuditTrail observer.
+ #
+ # ORM.observers.disable :observer_1, :observer_2
+ # # => disables Observer1 and Observer2 for all models.
+ #
+ # ORM.observers.disable :all
+ # # => disables all observers for all models.
+ #
+ # User.observers.disable :all do
+ # # all user observers are disabled for
+ # # just the duration of the block
+ # end
def disable(*observers, &block)
set_enablement(false, observers, &block)
end
+ # Enables one or more observers. This supports multiple forms:
+ #
+ # ORM.observers.enable :user_observer
+ # # => enables the UserObserver
+ #
+ # User.observers.enable AuditTrail
+ # # => enables the AuditTrail observer for User notifications.
+ # # Other models will not be affected (i.e. they will not
+ # # trigger notifications to AuditTrail if previously disabled)
+ #
+ # ORM.observers.enable :observer_1, :observer_2
+ # # => enables Observer1 and Observer2 for all models.
+ #
+ # ORM.observers.enable :all
+ # # => enables all observers for all models.
+ #
+ # User.observers.enable :all do
+ # # all user observers are enabled for
+ # # just the duration of the block
+ # end
+ #
+ # Note: all observers are enabled by default. This method is only
+ # useful when you have previously disabled one or more observers.
def enable(*observers, &block)
set_enablement(true, observers, &block)
end
@@ -40,7 +40,11 @@ def observers=(*values)
observers.replace(values.flatten)
end
- # Gets the current observers.
+ # 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)
def observers
@observers ||= ObserverArray.new(self)
end
@@ -222,7 +226,8 @@ def observed_classes #:nodoc:
self.class.observed_classes
end
- # Send observed_method(object) if the method exists.
+ # Send observed_method(object) if the method exists and
+ # the observer is enabled for the given object's class.
def update(observed_method, object) #:nodoc:
return unless respond_to?(observed_method)
return if disabled_for?(object)

0 comments on commit dd752a5

Please sign in to comment.