module ActiveSupport::Callbacks - activesupport-4.2.3 Documentation

# module ActiveSupport::Callbacks

Callbacks are code hooks that are run at key points in an object's life cycle. The typical use case is to have a base class define a set of callbacks relevant to the other functionality it supplies, so that subclasses can install callbacks that enhance or modify the base functionality without needing to override or redefine methods of the base class.

Mixing in this module allows you to define the events in the object's life cycle that will support callbacks (via `ClassMethods.define_callbacks`), set the instance methods, procs, or callback objects to be called (via `ClassMethods.set_callback`), and run the installed callbacks at the appropriate times (via `run_callbacks`).

Three kinds of callbacks are supported: before callbacks, run before a certain event; after callbacks, run after the event; and around callbacks, blocks that surround the event, triggering it when they yield. Callback code can be contained in instance methods, procs or lambdas, or callback objects that respond to certain predetermined methods. See `ClassMethods.set_callback` for details.

    class Record
      include ActiveSupport::Callbacks
      define_callbacks :save

      def save
        run_callbacks :save do
          puts "- save"
        end
      end
    end

    class PersonRecord < Record
      set_callback :save, :before, :saving_message
      def saving_message
        puts "saving..."
      end

      set_callback :save, :after do |object|
        puts "saved"
      end
    end

    person = PersonRecord.new
    person.save

Output:

    saving...
    - save
    saved

### Constants

CALLBACK_FILTER_TYPES

### Public Instance Methods

run_callbacks(kind) { || ... } click to toggle source

Runs the callbacks for the given event.

Calls the before and around callbacks in the order they were set, yields the block (if given one), and then runs the after callbacks in reverse order.

If the callback chain was halted, returns `false`. Otherwise returns the result of the block, `nil` if no callbacks have been set, or `true` if callbacks have been set but no block is given.

    run_callbacks :save do
      save
    end

    # File lib/active_support/callbacks.rb, line 80
    def run_callbacks(kind, &block)
      callbacks = send("_#{kind}_callbacks")

      if callbacks.empty?
        yield if block_given?
      else
        runner = callbacks.compile
        e = Filters::Environment.new(self, false, nil, block)
        runner.call(e).value
      end
    end

### Private Instance Methods

halted_callback_hook(filter) click to toggle source

A hook invoked every time a before callback is halted. This can be overridden in AS::Callback implementors in order to provide better debugging/logging.

    # File lib/active_support/callbacks.rb, line 97
    def halted_callback_hook(filter)
    end