Module: ActiveSupport::Callbacks::ClassMethods

Defined in:
lib/active_support/callbacks.rb

Instance Method Summary collapse

Instance Method Details

#__update_callbacks(name) ⇒ Object

This is used internally to append, prepend and skip callbacks to the CallbackChain.



686
687
688
689
690
691
 
# File 'lib/active_support/callbacks.rb', line 686

def __update_callbacks(name) # :nodoc:
  self.descendants.prepend(self).reverse_each do |target|
    chain = target.get_callbacks name
    yield target, chain.dup
  end
end

#define_callbacks(*names) ⇒ Object

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 has no effect if :terminator option is set to nil.

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



901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
 
# File 'lib/active_support/callbacks.rb', line 901

def define_callbacks(*names)
  options = names.extract_options!

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

    ([self] + self.descendants).each do |target|
      target.set_callbacks name, CallbackChain.new(name, options)
    end

    module_eval <<-RUBY, __FILE__, __LINE__ + 1
      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
    RUBY
  end
end

#normalize_callback_params(filters, block) ⇒ Object

:nodoc:



677
678
679
680
681
682
 
# File 'lib/active_support/callbacks.rb', line 677

def normalize_callback_params(filters, block) # :nodoc:
  type = CALLBACK_FILTER_TYPES.include?(filters.first) ? filters.shift : :before
  options = filters.extract_options!
  filters.unshift(block) if block
  [type, filters, options.dup]
end

#reset_callbacks(name) ⇒ Object

Remove all set callbacks for the given event.



811
812
813
814
815
816
817
818
819
820
821
 
# File 'lib/active_support/callbacks.rb', line 811

def reset_callbacks(name)
  callbacks = get_callbacks name

  self.descendants.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) ⇒ Object

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 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.

    If a proc is given, its body is evaluated in the context of the current object. It can also optionally accept the current object as an argument.

  • :unless - A symbol 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.

    If a proc is given, its body is evaluated in the context of the current object. It can also optionally accept the current object as an argument.

  • :prepend - If true, the callback will be prepended to the existing chain rather than appended.



737
738
739
740
741
742
743
744
745
746
747
748
749
 
# File 'lib/active_support/callbacks.rb', line 737

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) ⇒ Object

Skip a previously set callback. Like #set_callback, :if or :unless options may be passed in order to control when the callback is skipped.

Note: this example uses PersonRecord and #saving_message, which you can see defined here

class Writer < PersonRecord
  attr_accessor :age
  skip_callback :save, :before, :saving_message, if: -> { age > 18 }
end

When if option returns true, callback is skipped.

writer = Writer.new
writer.age = 20
writer.save

Output:

- save
saved

When if option returns false, callback is NOT skipped.

young_writer = Writer.new
young_writer.age = 17
young_writer.save

Output:

saving...
- save
saved

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



786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
 
# File 'lib/active_support/callbacks.rb', line 786

def skip_callback(name, *filter_list, &block)
  type, filters, options = normalize_callback_params(filter_list, block)

  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