Methods
D
R
S
Instance Public methods
define_callbacks(*callbacks)

Define sets of events in the object lifecycle 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 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 activesupport/lib/active_support/callbacks.rb, line 611
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
reset_callbacks(symbol)

Remove all set callbacks for the given event.

# File activesupport/lib/active_support/callbacks.rb, line 530
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.__define_runner(symbol)
  end

  self.send("_#{symbol}_callbacks=", callbacks.dup.clear)

  __define_runner(symbol)
end
set_callback(name, *filter_list, &block)

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.

Options
  • :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.

Per-key conditions

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 activesupport/lib/active_support/callbacks.rb, line 486
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_callback(name, *filter_list, &block)

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 activesupport/lib/active_support/callbacks.rb, line 511
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