ActiveSupport::Callbacks::ClassMethods
Methods
D
R
S
Instance Public methods
define_callbacks(*names)

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 before and around callbacks from being called and the event from being triggered. This should be a lambda to be executed. The current object and the result lambda of the callback will be provided to the terminator lambda.

    define_callbacks :validate, terminator: ->(target, result_lambda) { result_lambda.call == false }
    

    In this example, if any before validate callbacks returns false, any successive before and around callback is not executed.

    The default terminator halts the chain when a callback throws :abort.

  • :skip_after_callbacks_if_terminated - Determines if after callbacks should be terminated by the :terminator option. By default after callbacks are executed no matter if callback chain was terminated or not. This 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.

Notes

names passed to define_callbacks must not end with !, ? or =.

Calling define_callbacks multiple times with the same names will overwrite previous callbacks registered with set_callback.

# File activesupport/lib/active_support/callbacks.rb, line 815
        def define_callbacks(*names)
          options = names.extract_options!

          names.each do |name|
            name = name.to_sym

            set_callbacks name, CallbackChain.new(name, options)

            module_eval "              def _run_#{name}_callbacks(&block)
                run_callbacks #{name.inspect}, &block
              end

              def self._#{name}_callbacks
                get_callbacks(#{name.inspect})
              end

              def self._#{name}_callbacks=(value)
                set_callbacks(#{name.inspect}, value)
              end

              def _#{name}_callbacks
                __callbacks[#{name.inspect}]
              end
", __FILE__, __LINE__ + 1
          end
        end
reset_callbacks(name)

Remove all set callbacks for the given event.

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

  set_callbacks(name, callbacks.dup.clear)
end
set_callback(name, *filter_list, &block)

Install a callback for the given event.

set_callback :save, :before, :before_method
set_callback :save, :after,  :after_method, if: :condition
set_callback :save, :around, ->(r, block) { stuff; result = block.call; stuff }

The second argument 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_method

The callback can be specified as a symbol naming an instance method; as a proc, lambda, or block; 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, a string (deprecated) or an array of symbols, 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 (deprecated) or an array of symbols, 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 activesupport/lib/active_support/callbacks.rb, line 662
        def set_callback(name, *filter_list, &block)
          type, filters, options = normalize_callback_params(filter_list, block)

          if options[:if].is_a?(String) || options[:unless].is_a?(String)
            ActiveSupport::Deprecation.warn("              Passing string to :if and :unless conditional options is deprecated
              and will be removed in Rails 5.2 without replacement.
".squish)
          end

          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_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: -> { age > 18 }
end

An ArgumentError will be raised if the callback has not already been set (unless the :raise option is set to false).

# File activesupport/lib/active_support/callbacks.rb, line 693
        def skip_callback(name, *filter_list, &block)
          type, filters, options = normalize_callback_params(filter_list, block)

          if options[:if].is_a?(String) || options[:unless].is_a?(String)
            ActiveSupport::Deprecation.warn("              Passing string to :if and :unless conditional options is deprecated
              and will be removed in Rails 5.2 without replacement.
".squish)
          end

          options[:raise] = true unless options.key?(:raise)

          __update_callbacks(name) do |target, chain|
            filters.each do |filter|
              callback = chain.find { |c| c.matches?(type, filter) }

              if !callback && options[:raise]
                raise ArgumentError, "#{type.to_s.capitalize} #{name} callback #{filter.inspect} has not been defined"
              end

              if callback && (options.key?(:if) || options.key?(:unless))
                new_callback = callback.merge_conditional_options(chain, if_option: options[:if], unless_option: options[:unless])
                chain.insert(chain.index(callback), new_callback)
              end

              chain.delete(callback)
            end
            target.set_callbacks name, chain
          end
        end