set_callback

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.