From cb15fe55dab3287562f0f90d7a8ca1d1c9f5c162 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Mon, 30 Jul 2012 23:15:27 -0500 Subject: update ActiveModel::Observing documentation [ci skip] --- activemodel/lib/active_model/observing.rb | 150 +++++++++++++++++++++++++----- 1 file changed, 125 insertions(+), 25 deletions(-) (limited to 'activemodel/lib/active_model/observing.rb') diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index ca206ee9aa..1114ac962a 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -9,6 +9,7 @@ require 'active_support/core_ext/object/try' require 'active_support/descendants_tracker' module ActiveModel + # == Active Model Observers Activation module Observing extend ActiveSupport::Concern @@ -17,9 +18,7 @@ module ActiveModel end module ClassMethods - # == Active Model Observers Activation - # - # Activates the observers assigned. Examples: + # Activates the observers assigned. # # class ORM # include ActiveModel::Observing @@ -35,34 +34,95 @@ module ActiveModel # ORM.observers = Cacher, GarbageCollector # # Note: Setting this does not instantiate the observers yet. - # +instantiate_observers+ is called during startup, and before + # 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) + # 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 # => [#] 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 + # 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'" @@ -70,16 +130,47 @@ module ActiveModel observer_instances << observer end - # Notify list of observers of a change. + # 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 - # Total number of 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 + # count_observers is deprecated. Use #observers_count. def count_observers msg = "count_observers is deprecated in favor of observers_count" ActiveSupport::Deprecation.warn(msg) @@ -110,21 +201,30 @@ module ActiveModel end end - # Fires notifications to model's observers + # Notify a change to the list of observers. + # + # class Foo + # include ActiveModel::Observing # - # def save - # notify_observers(:before_save) - # ... - # notify_observers(:after_save) + # attr_accessor :status # end # - # Custom notifications can be sent in a similar fashion: + # class FooObserver < ActiveModel::Observer + # def on_spec(record, *args) + # record.status = true + # end + # end # - # notify_observers(:custom_notification, :foo) + # Foo.observers = FooObserver + # Foo.instantiate_observers # => [FooObserver] # - # This will call +custom_notification+, passing as arguments - # the current object and :foo. + # 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 @@ -238,7 +338,7 @@ 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, *extra_args, &block) #:nodoc: - return if !respond_to?(observed_method) || disabled_for?(object) + return if !respond_to?(observed_method) || disabled_for?(object) send(observed_method, object, *extra_args, &block) end -- cgit v1.2.3 From 1d537fdc47065d58ea268b6eac9593e559596431 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Mon, 30 Jul 2012 23:19:15 -0500 Subject: add :nodoc: to ActiveModel::Observing#inherited [ci skip] --- activemodel/lib/active_model/observing.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activemodel/lib/active_model/observing.rb') diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index 1114ac962a..aae0d3a2ef 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -195,7 +195,7 @@ module ActiveModel end # Notify observers when the observed class is subclassed. - def inherited(subclass) + def inherited(subclass) #:nodoc: super notify_observers :observed_class_inherited, subclass end -- cgit v1.2.3 From 7b7501b2e591718897f8d4a1d201b6d72f0fe7cd Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Tue, 31 Jul 2012 11:43:17 -0500 Subject: update ActiveModel::Observer documentation [ci skip] --- activemodel/lib/active_model/observing.rb | 53 +++++++++++++++++++------------ 1 file changed, 32 insertions(+), 21 deletions(-) (limited to 'activemodel/lib/active_model/observing.rb') diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index aae0d3a2ef..7da9246911 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -236,15 +236,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 Comment#save is finished. # # class ContactObserver < ActiveModel::Observer # def after_create(contact) @@ -261,44 +261,50 @@ 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 Observer.observe - # class method which takes either the concrete class (Product) or a symbol for that - # class (:product): + # 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") + # 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 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 + # 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 } @@ -307,6 +313,8 @@ module ActiveModel # 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 @@ -318,8 +326,11 @@ module ActiveModel 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 name[/(.*)Observer/, 1].try :constantize end @@ -327,7 +338,7 @@ module ActiveModel # Start observing the declared classes and their subclasses. # Called automatically by the instance method. - def initialize + def initialize #:nodoc: observed_classes.each { |klass| add_observer!(klass) } end @@ -355,7 +366,7 @@ module ActiveModel end # Returns true if notifications are disabled for this object. - def disabled_for?(object) + def disabled_for?(object) #:nodoc: klass = object.class return false unless klass.respond_to?(:observers) klass.observers.disabled_for?(self) -- cgit v1.2.3