aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--activesupport/lib/active_support/callbacks.rb42
1 files changed, 22 insertions, 20 deletions
diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb
index 92a4635011..8d71be1a4e 100644
--- a/activesupport/lib/active_support/callbacks.rb
+++ b/activesupport/lib/active_support/callbacks.rb
@@ -449,7 +449,9 @@ module ActiveSupport
# we convert :only and :except conditions into per-key conditions.
#
# before_filter :authenticate, :except => "index"
+ #
# becomes
+ #
# dispatch_callback :before, :authenticate, :per_key => {:unless => proc {|c| c.action_name == "index"}}
#
# Per-Key conditions are evaluated only once per use of a given key.
@@ -510,33 +512,33 @@ module ActiveSupport
__define_runner(symbol)
end
- # Define callbacks types.
- #
- # ==== Example
+ # Defines callbacks types:
#
# define_callbacks :validate
#
- # ==== Options
+ # This macro accepts the following options:
#
# * <tt>:terminator</tt> - Indicates when a before filter is considered
# to be halted.
#
# define_callbacks :validate, :terminator => "result == false"
#
- # In the example above, if any before validate callbacks returns false,
- # other callbacks are not executed. Defaults to "false".
+ # In the example above, if any before validate callbacks returns +false+,
+ # other callbacks are not executed. Defaults to "false", meaning no value
+ # halts the chain.
#
# * <tt>:rescuable</tt> - By default, after filters are not executed if
- # the given block or an before_filter raises an error. Supply :rescuable => true
- # to change this behavior.
+ # the given block or a before filter raises an error. Set this option to
+ # true to change this behavior.
#
# * <tt>:scope</tt> - Indicates which methods should be executed when a class
- # is given as callback:
+ # is given as callback. Defaults to <tt>[:kind]</tt>.
#
# class Audit
# def before(caller)
# puts 'Audit: before is called'
# end
+ #
# def before_save(caller)
# puts 'Audit: before_save is called'
# end
@@ -544,8 +546,10 @@ module ActiveSupport
#
# class Account
# include ActiveSupport::Callbacks
+ #
# define_callbacks :save
# set_callback :save, :before, Audit.new
+ #
# def save
# run_callbacks :save do
# puts 'save in main'
@@ -553,22 +557,20 @@ module ActiveSupport
# end
# end
#
- # In the above case if you execute Account.new.save then method "before" of Audit class
- # will be called. Now change the class "Account" and pass "scope" to method "define_callbacks".
+ # In the above case whenever you save an account the method <tt>Audit#before</tt> will
+ # be called. On the other hand
#
- # define_callbacks :save, :scope => [:kind, :name]
+ # define_callbacks :save, :scope => [:kind, :name]
#
- # Now if you invoke Account.new.save then method "before_save" of Audit will be called
- # instead of method "before".
+ # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling
+ # <tt>"#{kind}_#{name}"</tt> on the given instance. In this case "kind" is "before" and
+ # "name" is "save".
#
- # When you do not pass any scope then the default value of scope ":kind" is implicitly being
- # passed. In the above case method "before_save" is constructed by calling "#{kind}_#{name}"
- # in the given class. In this case "kind" is "before" and "name" is "save".
+ # A declaration like
#
- # Although ":kind" is the default scope that is passed, it is possible to not to make use of ":kind".
- # define_callbacks :save, :scope => [:name] . A declaration like this would call "save" method of
- # Audit class since ":kind" is skipped.
+ # define_callbacks :save, :scope => [:name]
#
+ # would call <tt>Audit#save</tt>.
#
def define_callbacks(*callbacks)
config = callbacks.last.is_a?(Hash) ? callbacks.pop : {}