Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Improve AMo observing docs

  • Loading branch information...
commit 48bc39e03a077ed9a0684a181c1180c7f53b0cad 1 parent 7c84bbf
@josh josh authored
Showing with 73 additions and 4 deletions.
  1. +73 −4 activemodel/lib/active_model/observing.rb
View
77 activemodel/lib/active_model/observing.rb
@@ -42,7 +42,7 @@ def instantiate_observers
# Wraps methods with before and after notifications.
#
- # wrap_with_notifications :create, :save, :update, :destroy
+ # wrap_with_notifications :create, :save, :update, :destroy
def wrap_with_notifications(*methods)
methods.each do |method|
class_eval(<<-EOS, __FILE__, __LINE__ + 1)
@@ -58,7 +58,7 @@ def #{method}_with_notifications(*args, &block)
end
protected
- def instantiate_observer(observer)
+ def instantiate_observer(observer) #:nodoc:
# string/symbol
if observer.respond_to?(:to_sym)
observer = observer.to_s.camelize.constantize.instance
@@ -78,12 +78,72 @@ def inherited(subclass)
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.changed
self.class.notify_observers(method, self)
end
end
+ # Observer classes respond to lifecycle 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. Example:
+ #
+ # class CommentObserver < ActiveModel::Observer
+ # def after_save(comment)
+ # Notifications.deliver_comment("admin@do.com", "New comment was posted", comment)
+ # 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.
+ #
class Observer
include Singleton
@@ -95,6 +155,15 @@ def observe(*models)
define_method(:observed_classes) { models }
end
+ # Returns an array of Classes to observe.
+ #
+ # You can override this instead of using the +observe+ helper.
+ #
+ # class AuditObserver < ActiveModel::Observer
+ # def self.observed_classes
+ # [AccountObserver, BalanceObserver]
+ # end
+ # end
def observed_classes
Array.wrap(observed_class)
end
@@ -115,7 +184,7 @@ def initialize
observed_classes.each { |klass| add_observer!(klass) }
end
- def observed_classes
+ def observed_classes #:nodoc:
self.class.observed_classes
end
@@ -132,7 +201,7 @@ def observed_class_inherited(subclass) #:nodoc:
end
protected
- def add_observer!(klass)
+ def add_observer!(klass) #:nodoc:
klass.add_observer(self)
end
end
Please sign in to comment.
Something went wrong with that request. Please try again.