doc/api/classes/ActiveRecord/Observer.html
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: ActiveRecord::Observer</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Class</strong></td>
<td class="class-name-in-header">ActiveRecord::Observer</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../files/vendor/rails/activerecord/lib/active_record/observer_rb.html">
vendor/rails/activerecord/lib/active_record/observer.rb
</a>
<br />
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Parent:</strong></td>
<td>
Object
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
<a href="Observer.html">Observer</a> 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:
</p>
<pre>
class CommentObserver < ActiveRecord::Observer
def after_save(comment)
Notifications.deliver_comment("admin@do.com", "New comment was posted", comment)
end
end
</pre>
<p>
This <a href="Observer.html">Observer</a> sends an email when a
Comment#save is finished.
</p>
<pre>
class ContactObserver < ActiveRecord::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
</pre>
<p>
This <a href="Observer.html">Observer</a> uses logger to log when specific
callbacks are triggered.
</p>
<h2>Observing a class that can‘t be inferred</h2>
<p>
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 <a
href="Observer.html#M000991">Observer.observe</a> class method:
</p>
<pre>
class AuditObserver < ActiveRecord::Observer
observe Account
def after_update(account)
AuditTrail.new(account, "UPDATED")
end
end
</pre>
<p>
If the audit observer needs to watch more than one kind of object, this can
be specified with multiple arguments:
</p>
<pre>
class AuditObserver < ActiveRecord::Observer
observe Account, Balance
def after_update(record)
AuditTrail.new(record, "UPDATED")
end
end
</pre>
<p>
The AuditObserver will now act on both updates to Account and Balance by
treating them both as records.
</p>
<h2>Available callback methods</h2>
<p>
The observer can implement callback methods for each of the methods
described in the <a href="Callbacks.html">Callbacks</a> module.
</p>
<h2>Storing Observers in Rails</h2>
<p>
If you‘re using Active Record within Rails, observer classes are
usually stored in app/models with the naming convention of
app/models/audit_observer.rb.
</p>
<h2>Configuration</h2>
<p>
In order to activate an observer, list it in the
<tt>config.active_record.observers</tt> configuration setting in your
<tt>config/environment.rb</tt> file.
</p>
<pre>
config.active_record.observers = :comment_observer, :signup_observer
</pre>
<p>
Observers will not be invoked unless you define these in your application
configuration.
</p>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000996">add_observer!</a>
<a href="#M000993">new</a>
<a href="#M000991">observe</a>
<a href="#M000992">observed_class</a>
<a href="#M000994">observed_classes</a>
<a href="#M000995">observed_subclasses</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="includes">
<h3 class="section-bar">Included Modules</h3>
<div id="includes-list">
<span class="include-name">Singleton</span>
<span class="include-name">Reloadable::Deprecated</span>
</div>
</div>
<div id="section">
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000993" class="method-detail">
<a name="M000993"></a>
<div class="method-heading">
<a href="#M000993" class="method-signature">
<span class="method-name">new</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Start observing the declared classes and their subclasses.
</p>
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000993-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000993-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 148</span>
148: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">initialize</span>
149: <span class="ruby-constant">Set</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">observed_classes</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">observed_subclasses</span>).<span class="ruby-identifier">each</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">klass</span><span class="ruby-operator">|</span> <span class="ruby-identifier">add_observer!</span> <span class="ruby-identifier">klass</span> }
150: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<div id="method-M000991" class="method-detail">
<a name="M000991"></a>
<div class="method-heading">
<a href="#M000991" class="method-signature">
<span class="method-name">observe</span><span class="method-args">(*models)</span>
</a>
</div>
<div class="method-description">
<p>
Attaches the observer to the supplied model classes.
</p>
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000991-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000991-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 136</span>
136: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">observe</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">models</span>)
137: <span class="ruby-identifier">define_method</span>(<span class="ruby-identifier">:observed_classes</span>) { <span class="ruby-constant">Set</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">models</span>) }
138: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<div id="method-M000992" class="method-detail">
<a name="M000992"></a>
<div class="method-heading">
<a href="#M000992" class="method-signature">
<span class="method-name">observed_class</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
The class observed by default is inferred from the observer‘s class
name:
</p>
<pre>
assert_equal [Person], PersonObserver.observed_class
</pre>
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000992-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000992-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 142</span>
142: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">observed_class</span>
143: <span class="ruby-identifier">name</span>.<span class="ruby-identifier">scan</span>(<span class="ruby-regexp re">/(.*)Observer/</span>)[<span class="ruby-value">0</span>][<span class="ruby-value">0</span>].<span class="ruby-identifier">constantize</span>
144: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<h3 class="section-bar">Protected Instance methods</h3>
<div id="method-M000996" class="method-detail">
<a name="M000996"></a>
<div class="method-heading">
<a href="#M000996" class="method-signature">
<span class="method-name">add_observer!</span><span class="method-args">(klass)</span>
</a>
</div>
<div class="method-description">
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000996-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000996-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 173</span>
173: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">add_observer!</span>(<span class="ruby-identifier">klass</span>)
174: <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">add_observer</span>(<span class="ruby-keyword kw">self</span>)
175: <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">class_eval</span> <span class="ruby-value str">'def after_find() end'</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-identifier">:after_find</span>)
176: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<div id="method-M000994" class="method-detail">
<a name="M000994"></a>
<div class="method-heading">
<a href="#M000994" class="method-signature">
<span class="method-name">observed_classes</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000994-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000994-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 165</span>
165: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">observed_classes</span>
166: <span class="ruby-constant">Set</span>.<span class="ruby-identifier">new</span>([<span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">observed_class</span>].<span class="ruby-identifier">flatten</span>)
167: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<div id="method-M000995" class="method-detail">
<a name="M000995"></a>
<div class="method-heading">
<a href="#M000995" class="method-signature">
<span class="method-name">observed_subclasses</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000995-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000995-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/observer.rb, line 169</span>
169: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">observed_subclasses</span>
170: <span class="ruby-identifier">observed_classes</span>.<span class="ruby-identifier">sum</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">:subclasses</span>)
171: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>