Module: ActiveSupport::Callbacks::ClassMethods
- Defined in:
- lib/active_support/callbacks.rb
Instance Method Summary collapse
-
#__update_callbacks(name) ⇒ Object
This is used internally to append, prepend and skip callbacks to the CallbackChain.
-
#define_callbacks(*names) ⇒ Object
Define sets of events in the object life cycle that support callbacks.
-
#normalize_callback_params(filters, block) ⇒ Object
:nodoc:.
-
#reset_callbacks(name) ⇒ Object
Remove all set callbacks for the given event.
-
#set_callback(name, *filter_list, &block) ⇒ Object
Install a callback for the given event.
-
#skip_callback(name, *filter_list, &block) ⇒ Object
Skip a previously set callback.
Instance Method Details
#__update_callbacks(name) ⇒ Object
This is used internally to append, prepend and skip callbacks to the CallbackChain.
600 601 602 603 604 605 |
# File 'lib/active_support/callbacks.rb', line 600 def __update_callbacks(name) #:nodoc: ([self] + ActiveSupport::DescendantsTracker.descendants(self)).reverse.each do |target| chain = target.get_callbacks name yield target, chain.dup end end |
#define_callbacks(*names) ⇒ Object
Define sets of events in the object life cycle that support callbacks.
define_callbacks :validate
define_callbacks :initialize, :save, :destroy
Options
-
: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 tofalse
, 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 handdefine_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
.
761 762 763 764 765 766 767 768 769 770 771 772 773 774 |
# File 'lib/active_support/callbacks.rb', line 761 def define_callbacks(*names) = names. if .key?(:terminator) && String === [:terminator] ActiveSupport::Deprecation.warn "String based terminators are deprecated, please use a lambda" value = [:terminator] line = class_eval "lambda { |result| #{value} }", __FILE__, __LINE__ [:terminator] = lambda { |target, result| target.instance_exec(result, &line) } end names.each do |name| class_attribute "_#{name}_callbacks" set_callbacks name, CallbackChain.new(name, ) end end |
#normalize_callback_params(filters, block) ⇒ Object
:nodoc:
591 592 593 594 595 596 |
# File 'lib/active_support/callbacks.rb', line 591 def normalize_callback_params(filters, block) # :nodoc: type = CALLBACK_FILTER_TYPES.include?(filters.first) ? filters.shift : :before = filters. filters.unshift(block) if block [type, filters, .dup] end |
#reset_callbacks(name) ⇒ Object
Remove all set callbacks for the given event.
681 682 683 684 685 686 687 688 689 690 691 |
# File 'lib/active_support/callbacks.rb', line 681 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 |
#set_callback(name, *filter_list, &block) ⇒ Object
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.
Options
-
:if
- A symbol naming an instance method or a proc; the callback will be called only when it returns atrue
value. -
:unless
- A symbol naming an instance method or a proc; the callback will be called only when it returns afalse
value. -
:prepend
- Iftrue
, the callback will be prepended to the existing chain rather than appended.
642 643 644 645 646 647 648 649 650 651 652 653 |
# File 'lib/active_support/callbacks.rb', line 642 def set_callback(name, *filter_list, &block) type, filters, = normalize_callback_params(filter_list, block) self_chain = get_callbacks name mapped = filters.map do |filter| Callback.build(self_chain, filter, type, ) end __update_callbacks(name) do |target, chain| [:prepend] ? chain.prepend(*mapped) : chain.append(*mapped) target.set_callbacks name, chain end end |
#skip_callback(name, *filter_list, &block) ⇒ Object
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
662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 |
# File 'lib/active_support/callbacks.rb', line 662 def skip_callback(name, *filter_list, &block) type, filters, = 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 && .any? new_filter = filter.merge(chain, ) chain.insert(chain.index(filter), new_filter) end chain.delete(filter) end target.set_callbacks name, chain end end |