# File lib/active_support/callbacks.rb, line 413 def __callback_runner_name(key, kind) "_run__#{self.name.hash.abs}__#{kind}__#{key.hash.abs}__callbacks" end
# File lib/active_support/callbacks.rb, line 408 def __reset_runner(symbol) name = __callback_runner_name(nil, symbol) undef_method(name) if method_defined?(name) end
Define sets of events in the object lifecycle that support callbacks.
define_callbacks :validate define_callbacks :initialize, :save, :destroy
:terminator
- Determines when a before filter will halt the
callback chain, preventing following callbacks from being called and the
event from being triggered. This is a string to be eval'ed. The result
of the callback is available in the result
variable.
define_callbacks :validate, :terminator => "result == false"
In this example, if any before validate callbacks returns
false
, other callbacks are not executed. Defaults to “false”,
meaning no value halts the chain.
:rescuable
- By default, after filters are not executed if the
given block or a before filter raises an error. By setting this option to
true
exception raised by given block is stored and after
executing all the after callbacks the stored exception is raised.
:scope
- Indicates which methods should be executed when an
object is used as a callback.
class Audit def before(caller) puts 'Audit: before is called' end def before_save(caller) puts 'Audit: before_save is called' end end class Account include ActiveSupport::Callbacks define_callbacks :save set_callback :save, :before, Audit.new def save run_callbacks :save do puts 'save in main' end end end
In the above case whenever you save an account the method
Audit#before
will be called. On the other hand
define_callbacks :save, :scope => [:kind, :name]
would trigger Audit#before_save
instead. That's
constructed by calling #{kind}_#{name}
on the given instance.
In this case “kind” is “before” and “name” is “save”. In this context
:kind
and :name
have special meanings:
:kind
refers to the kind of callback (before/after/around) and
:name
refers to the method on which callbacks are being
defined.
A declaration like
define_callbacks :save, :scope => [:name]
would call Audit#save
.
# File lib/active_support/callbacks.rb, line 616 def define_callbacks(*callbacks) config = callbacks.last.is_a?(Hash) ? callbacks.pop : {} callbacks.each do |callback| class_attribute "_#{callback}_callbacks" send("_#{callback}_callbacks=", CallbackChain.new(callback, config)) __define_runner(callback) end end
Remove all set callbacks for the given event.
# File lib/active_support/callbacks.rb, line 535 def reset_callbacks(symbol) callbacks = send("_#{symbol}_callbacks") ActiveSupport::DescendantsTracker.descendants(self).each do |target| chain = target.send("_#{symbol}_callbacks").dup callbacks.each { |c| chain.delete(c) } target.send("_#{symbol}_callbacks=", chain) target.__reset_runner(symbol) end self.send("_#{symbol}_callbacks=", callbacks.dup.clear) __reset_runner(symbol) end
Install a callback for the given event.
set_callback :save, :before, :before_meth set_callback :save, :after, :after_meth, :if => :condition set_callback :save, :around, lambda { |r| stuff; result = yield; stuff }
The second arguments indicates whether the callback is to be run
:before
, :after
, or :around
the
event. If omitted, :before
is assumed. This means the first
example above can also be written as:
set_callback :save, :before_meth
The callback can specified as a symbol naming an instance method; as a
proc, lambda, or block; as a string to be instance evaluated; or as an
object that responds to a certain method determined by the
:scope
argument to define_callback
.
If a proc, lambda, or block is given, its body is evaluated in the context of the current object. It can also optionally accept the current object as an argument.
Before and around callbacks are called in the order that they are set; after callbacks are called in the reverse order.
Around callbacks can access the return value from the event, if it
wasn't halted, from the yield
call.
:if
- A symbol naming an instance method or a proc; the
callback will be called only when it returns a true value.
:unless
- A symbol naming an instance method or a proc; the
callback will be called only when it returns a false value.
:prepend
- If true, the callback will be prepended to the
existing chain rather than appended.
:per_key
- A hash with :if
and
:unless
options; see “Per-key conditions” below.
When creating or skipping callbacks, you can specify conditions that are always the same for a given key. For instance, in Action Pack, we convert :only and :except conditions into per-key conditions.
before_filter :authenticate, :except => "index"
becomes
set_callback :process_action, :before, :authenticate, :per_key => {:unless => proc {|c| c.action_name == "index"}}
Per-key conditions are evaluated only once per use of a given key. In the case of the above example, you would do:
run_callbacks(:process_action, action_name) { ... dispatch stuff ... }
In that case, each action_name would get its own compiled callback method that took into consideration the per_key conditions. This is a speed improvement for ActionPack.
# File lib/active_support/callbacks.rb, line 491 def set_callback(name, *filter_list, &block) mapped = nil __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options| mapped ||= filters.map do |filter| Callback.new(chain, filter, type, options.dup, self) end filters.each do |filter| chain.delete_if {|c| c.matches?(type, filter) } end options[:prepend] ? chain.unshift(*(mapped.reverse)) : chain.push(*mapped) target.send("_#{name}_callbacks=", chain) end end
Skip a previously set callback. Like set_callback
,
:if
or :unless
options may be passed in order to
control when the callback is skipped.
class Writer < Person skip_callback :validate, :before, :check_membership, :if => lambda { self.age > 18 } end
# File lib/active_support/callbacks.rb, line 516 def skip_callback(name, *filter_list, &block) __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options| filters.each do |filter| filter = chain.find {|c| c.matches?(type, filter) } if filter && options.any? new_filter = filter.clone(chain, self) chain.insert(chain.index(filter), new_filter) new_filter.recompile!(options, options[:per_key] || {}) end chain.delete(filter) end target.send("_#{name}_callbacks=", chain) end end