Define sets of events in the object life cycle 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 should be a lambda to be executed. The
current object and the return result of the callback will be called with
the lambda.
define_callbacks :validate, terminator: ->(target, result) { 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.
:skip_after_callbacks_if_terminated
- Determines if after
callbacks should be terminated by the :terminator
option. By
default after callbacks executed no matter if callback chain was terminated
or not. Option makes sense only when :terminator
option is
specified.
: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
.
NOTE: method_name
passed to `define_model_callbacks` must not
end with `!`, `?` or `=`.
# File lib/active_support/callbacks.rb, line 769 def define_callbacks(*names) options = names.extract_options! names.each do |name| class_attribute "_#{name}_callbacks", instance_writer: false set_callbacks name, CallbackChain.new(name, options) module_eval " def _run_#{name}_callbacks(&block) __run_callbacks__(_#{name}_callbacks, &block) end ", __FILE__, __LINE__ + 1 end end
Remove all set callbacks for the given event.
# File lib/active_support/callbacks.rb, line 686 def reset_callbacks(name) callbacks = get_callbacks name ActiveSupport::DescendantsTracker.descendants(self).each do |target| chain = target.get_callbacks(name).dup callbacks.each { |c| chain.delete(c) } target.set_callbacks name, chain end self.set_callbacks name, callbacks.dup.clear 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, ->(r, block) { stuff; result = block.call; 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 be 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_callbacks
.
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, a string or an array of symbols and strings,
each naming an instance method or a proc; the callback will be called only
when they all return a true value.
:unless
- A symbol, a string or an array of symbols and
strings, each naming an instance method or a proc; the callback will be
called only when they all return a false value.
:prepend
- If true
, the callback will be
prepended to the existing chain rather than appended.
# File lib/active_support/callbacks.rb, line 647 def set_callback(name, *filter_list, &block) type, filters, options = normalize_callback_params(filter_list, block) self_chain = get_callbacks name mapped = filters.map do |filter| Callback.build(self_chain, filter, type, options) end __update_callbacks(name) do |target, chain| options[:prepend] ? chain.prepend(*mapped) : chain.append(*mapped) target.set_callbacks name, 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: -> { self.age > 18 } end
# File lib/active_support/callbacks.rb, line 667 def skip_callback(name, *filter_list, &block) type, filters, options = normalize_callback_params(filter_list, block) __update_callbacks(name) do |target, chain| filters.each do |filter| filter = chain.find {|c| c.matches?(type, filter) } if filter && options.any? new_filter = filter.merge(chain, options) chain.insert(chain.index(filter), new_filter) end chain.delete(filter) end target.set_callbacks name, chain end end
# File lib/active_support/callbacks.rb, line 786 def get_callbacks(name) send "_#{name}_callbacks" end
# File lib/active_support/callbacks.rb, line 790 def set_callbacks(name, callbacks) send "_#{name}_callbacks=", callbacks end