From 5932357f1983899762e2a81f1c5974c151c6414a Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Wed, 5 Mar 2008 10:53:34 +0000 Subject: Docs for ActiveSupport::Callbacks. Closes #11254 [ernesto.jimenez] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8984 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activesupport/lib/active_support/callbacks.rb | 120 ++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb index ac9f1a9d5f..c463bfda54 100644 --- a/activesupport/lib/active_support/callbacks.rb +++ b/activesupport/lib/active_support/callbacks.rb @@ -1,4 +1,80 @@ module ActiveSupport + # Callbacks are hooks into the lifecycle of an object that allow you to trigger logic + # before or after an alteration of the object state. + # + # This mixing this module allos you to define callbacks in your class. + # + # Example: + # class Storage + # include ActiveSupport::Callbacks + # + # define_callbacks :before_save, :after_save + # end + # + # class ConfigStorage < Storage + # before_save :saving_message + # def saving_message + # puts "saving..." + # end + # + # after_save do |object| + # puts "saved" + # end + # + # def save + # run_callbacks(:before_save) + # puts "- save" + # run_callbacks(:after_save) + # end + # end + # + # config = ConfigStorage.new + # config.save + # + # Output: + # saving... + # - save + # saved + # + # Callbacks from parent classes are inherited. + # + # Example: + # class Storage + # include ActiveSupport::Callbacks + # + # define_callbacks :before_save, :after_save + # + # before_save :prepare + # def prepare + # puts "preparing save" + # end + # end + # + # class ConfigStorage < Storage + # before_save :saving_message + # def saving_message + # puts "saving..." + # end + # + # after_save do |object| + # puts "saved" + # end + # + # def save + # run_callbacks(:before_save) + # puts "- save" + # run_callbacks(:after_save) + # end + # end + # + # config = ConfigStorage.new + # config.save + # + # Output: + # preparing save + # saving... + # - save + # saved module Callbacks class Callback def self.run(callbacks, object, options = {}, &terminator) @@ -87,6 +163,50 @@ module ActiveSupport end end + # Runs all the callbacks defined for the given options. + # + # If a block is given it will be called after each callback reciving as arguments: + # + # * the result from the callback + # * the object which has the callback + # + # If the result from the block evaluates as false, callback chain is stopped. + # + # Example: + # class Storage + # include ActiveSupport::Callbacks + # + # define_callbacks :before_save, :after_save + # end + # + # class ConfigStorage < Storage + # before_save :pass + # before_save :pass + # before_save :stop + # before_save :pass + # + # def pass + # puts "pass" + # end + # + # def stop + # puts "stop" + # return false + # end + # + # def save + # result = run_callbacks(:before_save) { |result, object| result == false } + # puts "- save" if result + # end + # end + # + # config = ConfigStorage.new + # config.save + # + # Output: + # pass + # pass + # stop def run_callbacks(kind, options = {}, &block) Callback.run(self.class.send("#{kind}_callback_chain"), self, options, &block) end -- cgit v1.2.3