aboutsummaryrefslogtreecommitdiffstats
path: root/activemodel/lib
diff options
context:
space:
mode:
authorMyron Marston <myron.marston@gmail.com>2011-05-06 09:59:57 -0700
committerMyron Marston <myron.marston@gmail.com>2011-05-06 10:00:14 -0700
commit99363dcf60a97fa25e94cc4217f9befeafbb6b70 (patch)
treecfcf6dc944745c9976ac3144f34161bf48738195 /activemodel/lib
parent9c2c25c1a1343937e96eed81e38ef4f9fb06ce11 (diff)
downloadrails-99363dcf60a97fa25e94cc4217f9befeafbb6b70.tar.gz
rails-99363dcf60a97fa25e94cc4217f9befeafbb6b70.tar.bz2
rails-99363dcf60a97fa25e94cc4217f9befeafbb6b70.zip
Add documentation for new observer enable/disable feature.
Diffstat (limited to 'activemodel/lib')
-rw-r--r--activemodel/lib/active_model/observer_array.rb45
-rw-r--r--activemodel/lib/active_model/observing.rb9
2 files changed, 51 insertions, 3 deletions
diff --git a/activemodel/lib/active_model/observer_array.rb b/activemodel/lib/active_model/observer_array.rb
index ab7f86007f..5fb73f1c78 100644
--- a/activemodel/lib/active_model/observer_array.rb
+++ b/activemodel/lib/active_model/observer_array.rb
@@ -2,7 +2,7 @@ require 'set'
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)
@@ -10,14 +10,57 @@ module ActiveModel
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
diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb
index cfe71074a5..4682ae07ef 100644
--- a/activemodel/lib/active_model/observing.rb
+++ b/activemodel/lib/active_model/observing.rb
@@ -40,7 +40,11 @@ module ActiveModel
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 @@ module ActiveModel
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)