Module: MotionSupport::Callbacks::ClassMethods

Defined in:
motion/callbacks.rb

Instance Method Summary collapse

Instance Method Details

#__callback_runner_name(kind) ⇒ Object 



328
329
330
 
# File 'motion/callbacks.rb', line 328

def __callback_runner_name(kind)
  __callback_runner_name_cache[kind]
end

#__callback_runner_name_cache ⇒ Object 



320
321
322
 
# File 'motion/callbacks.rb', line 320

def __callback_runner_name_cache
  @__callback_runner_name_cache ||= Hash.new {|cache, kind| cache[kind] = __generate_callback_runner_name(kind) }
end

#__define_callbacks(kind, object) ⇒ Object

This method defines callback chain method for the given kind if it was not yet defined. This generated method plays caching role.



303
304
305
306
307
308
309
310
311
312
313
 
# File 'motion/callbacks.rb', line 303

def __define_callbacks(kind, object) #:nodoc:
  name = __callback_runner_name(kind)
  unless object.respond_to?(name, true)
    block = object.send("_#{kind}_callbacks").compile
    define_method name do |&blk|
      block.call(self, &blk)
    end
    protected name.to_sym
  end
  name
end

#__generate_callback_runner_name(kind) ⇒ Object 



324
325
326
 
# File 'motion/callbacks.rb', line 324

def __generate_callback_runner_name(kind)
  "_run__#{self.name.hash.abs}__#{kind}__callbacks"
end

#__reset_runner(symbol) ⇒ Object 



315
316
317
318
 
# File 'motion/callbacks.rb', line 315

def __reset_runner(symbol)
  name = __callback_runner_name(symbol)
  undef_method(name) if method_defined?(name)
end

#__update_callbacks(name, filters = [], block = nil) ⇒ Object

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



334
335
336
337
338
339
340
341
342
343
344
 
# File 'motion/callbacks.rb', line 334

def __update_callbacks(name, filters = [], block = nil) #:nodoc:
  type = [:before, :after, :around].include?(filters.first) ? filters.shift : :before
  options = filters.last.is_a?(Hash) ? filters.pop : {}
  filters.unshift(block) if block

  ([self] + MotionSupport::DescendantsTracker.descendants(self)).reverse.each do |target|
    chain = target.send("_#{name}_callbacks")
    yield target, chain.dup, type, filters, options
    target.__reset_runner(name)
  end
end

#define_callbacks(*callbacks) ⇒ Object

Define sets of events in the object lifecycle 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 is a string to be eval’ed. The result of the callback is available in the result variable.

    define_callbacks :validate, terminator: '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 MotionSupport::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.



502
503
504
505
506
507
508
 
# File 'motion/callbacks.rb', line 502

def define_callbacks(*callbacks)
  config = callbacks.last.is_a?(Hash) ? callbacks.pop : {}
  callbacks.each do |callback|
    class_attribute "_#{callback}_callbacks"
    send("_#{callback}_callbacks=", CallbackChain.new(callback, config))
  end
end

#reset_callbacks(symbol) ⇒ Object

Remove all set callbacks for the given event.



420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'motion/callbacks.rb', line 420

def reset_callbacks(symbol)
  callbacks = send("_#{symbol}_callbacks")

  MotionSupport::DescendantsTracker.descendants(self).each do |target|
    chain = target.send("_#{symbol}_callbacks").dup
    callbacks.each { |c| chain.delete(c) }
    target.send("_#{symbol}_callbacks=", chain)
    target.__reset_runner(symbol)
  end

  self.send("_#{symbol}_callbacks=", callbacks.dup.clear)

  __reset_runner(symbol)
end

#set_callback(name, *filter_list, &block) ⇒ Object

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

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.



381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'motion/callbacks.rb', line 381

def set_callback(name, *filter_list, &block)
  mapped = nil

  __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options|
    mapped ||= filters.map do |filter|
      Callback.new(chain, filter, type, options.dup, self)
    end

    options[:prepend] ? chain.prepend(*mapped) : chain.append(*mapped)

    target.send("_#{name}_callbacks=", 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.

class Writer < Person
   skip_callback :validate, :before, :check_membership, if: -> { self.age > 18 }
end



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'motion/callbacks.rb', line 402

def skip_callback(name, *filter_list, &block)
  __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options|
    filters.each do |filter|
      filter = chain.find {|c| c.matches?(type, filter) }

      if filter && options.any?
        new_filter = filter.clone(chain, self)
        chain.insert(chain.index(filter), new_filter)
        new_filter.recompile!(options)
      end

      chain.delete(filter)
    end
    target.send("_#{name}_callbacks=", chain)
  end
end