Module: ActiveSupport::Callbacks::ClassMethods

Defined in:
activesupport/lib/active_support/callbacks.rb

Instance Method Summary (collapse)

Instance Method Details

- (Object) __update_callbacks(name)

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



564
565
566
567
568
569
# File 'activesupport/lib/active_support/callbacks.rb', line 564

def __update_callbacks(name) #:nodoc:
  ([self] + ActiveSupport::DescendantsTracker.descendants(self)).reverse.each do |target|
    chain = target.get_callbacks name
    yield target, chain.dup
  end
end

- (Object) 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 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.



725
726
727
728
729
730
731
732
733
734
735
736
737
738
# File 'activesupport/lib/active_support/callbacks.rb', line 725

def define_callbacks(*names)
  options = names.extract_options!
  if options.key?(:terminator) && String === options[:terminator]
    ActiveSupport::Deprecation.warn "String based terminators are deprecated, please use a lambda"
    value = options[:terminator]
    line = class_eval "lambda { |result| #{value} }", __FILE__, __LINE__
    options[:terminator] = lambda { |target, result| target.instance_exec(result, &line) }
  end

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

- (Object) normalize_callback_params(filters, block)

:nodoc:



555
556
557
558
559
560
# File 'activesupport/lib/active_support/callbacks.rb', line 555

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

- (Object) reset_callbacks(name)

Remove all set callbacks for the given event.



645
646
647
648
649
650
651
652
653
654
655
# File 'activesupport/lib/active_support/callbacks.rb', line 645

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

- (Object) set_callback(name, *filter_list, &block)

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



606
607
608
609
610
611
612
613
614
615
616
617
# File 'activesupport/lib/active_support/callbacks.rb', line 606

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

- (Object) 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: -> { self.age > 18 }
end


626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
# File 'activesupport/lib/active_support/callbacks.rb', line 626

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