module ActiveSupport::Callbacks::ClassMethods - activesupport-4.2.4 Documentation

# module ActiveSupport::Callbacks::ClassMethods

### Public Instance Methods

define_callbacks(*names) click to toggle source

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 to `false`, 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 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`.

NOTE: `method_name` passed to `define_model_callbacks` must not end with `!`, `?` or `=`.

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

            names.each do |name|
              class_attribute "_#{name}_callbacks"
              set_callbacks name, CallbackChain.new(name, options)

              module_eval "            def _run_#{name}_callbacks(&block)
                  __run_callbacks__(_#{name}_callbacks, &block)
                end
    ", __FILE__, __LINE__ + 1
            end
          end

reset_callbacks(name) click to toggle source

Remove all set callbacks for the given event.

    # File lib/active_support/callbacks.rb, line 686
    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) click to toggle source

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, a string or an array of symbols and strings, 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 or an array of symbols and strings, 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 lib/active_support/callbacks.rb, line 647
    def set_callback(name, *filter_list, &block)
      type, filters, options = normalize_callback_params(filter_list, block)
      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) click to toggle source

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

    # File lib/active_support/callbacks.rb, line 667
    def skip_callback(name, *filter_list, &block)
      type, filters, options = 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 && options.any?
            new_filter = filter.merge(chain, options)
            chain.insert(chain.index(filter), new_filter)
          end

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

### Protected Instance Methods

get_callbacks(name) click to toggle source

    # File lib/active_support/callbacks.rb, line 786
    def get_callbacks(name)
      send "_#{name}_callbacks"
    end

set_callbacks(name, callbacks) click to toggle source

    # File lib/active_support/callbacks.rb, line 790
    def set_callbacks(name, callbacks)
      send "_#{name}_callbacks=", callbacks
    end