diff options
Diffstat (limited to 'activemodel/lib/active_model/callbacks.rb')
| -rw-r--r-- | activemodel/lib/active_model/callbacks.rb | 104 |
1 files changed, 73 insertions, 31 deletions
diff --git a/activemodel/lib/active_model/callbacks.rb b/activemodel/lib/active_model/callbacks.rb index f66a1ddcaa..a7e0cf90c1 100644 --- a/activemodel/lib/active_model/callbacks.rb +++ b/activemodel/lib/active_model/callbacks.rb @@ -1,6 +1,52 @@ require 'active_support/callbacks' module ActiveModel + # == Active Model Callbacks + # + # Provides an interface for any class to have Active Record like callbacks. + # + # Like the Active Record methods, the call back chain is aborted as soon as + # one of the methods in the chain returns false. + # + # First, extend ActiveModel::Callbacks from the class you are creating: + # + # class MyModel + # extend ActiveModel::Callbacks + # end + # + # Then define a list of methods that you want call backs attached to: + # + # define_model_callbacks :create, :update + # + # This will provide all three standard callbacks (before, around and after) around + # both the :create and :update methods. To implement, you need to wrap the methods + # you want call backs on in a block so that the call backs get a chance to fire: + # + # def create + # _run_create_callbacks do + # # Your create action methods here + # end + # end + # + # The _run_<method_name>_callbacks methods are dynamically created when you extend + # the <tt>ActiveModel::Callbacks</tt> module. + # + # Then in your class, you can use the +before_create+, +after_create+ and +around_create+ + # methods, just as you would in an Active Record module. + # + # before_create :action_before_create + # + # def action_before_create + # # Your code here + # end + # + # You can choose not to have all three callbacks by passing an hash to the + # define_model_callbacks method. + # + # define_model_callbacks :create, :only => :after, :before + # + # Would only create the after_create and before_create callback methods in your + # class. module Callbacks def self.extended(base) base.class_eval do @@ -8,43 +54,39 @@ module ActiveModel end end - # Define callbacks similar to ActiveRecord ones. It means: - # - # * The callback chain is aborted whenever the block given to - # _run_callbacks returns false. - # - # * If a class is given to the fallback, it will search for - # before_create, around_create and after_create methods. - # - # == Usage - # - # First you need to define which callbacks your model will have: + # define_model_callbacks accepts all options define_callbacks does, in case you + # want to overwrite a default. Besides that, it also accepts an :only option, + # where you can choose if you want all types (before, around or after) or just some. # + # define_model_callbacks :initializer, :only => :after + # + # Note, the <tt>:only => <type></tt> hash will apply to all callbacks defined on + # that method call. To get around this you can call the define_model_callbacks + # method as many times as you need. + # + # define_model_callbacks :create, :only => :after + # define_model_callbacks :update, :only => :before + # define_model_callbacks :destroy, :only => :around + # + # Would create +after_create+, +before_update+ and +around_destroy+ methods only. + # + # You can pass in a class to before_<type>, after_<type> and around_<type>, in which + # case the call back will call that class's <action>_<type> method passing the object + # that the callback is being called on. + # # class MyModel + # extend ActiveModel::Callbacks # define_model_callbacks :create + # + # before_create AnotherClass # end - # - # This will define three class methods: before_create, around_create, - # and after_create. They accept a symbol, a string, an object or a block. - # - # After you create a callback, you need to tell when they are executed. - # For example, you could do: - # - # def create - # _run_create_callbacks do - # super + # + # class AnotherClass + # def self.before_create( obj ) + # # obj is the MyModel instance that the callback is being called on # end # end - # - # == Options - # - # define_model_callbacks accepts all options define_callbacks does, in - # case you want to overwrite a default. Besides that, it also accepts - # an :only option, where you can choose if you want all types (before, - # around or after) or just some: - # - # define_model_callbacks :initializer, :only => :after - # + # def define_model_callbacks(*callbacks) options = callbacks.extract_options! options = { :terminator => "result == false", :scope => [:kind, :name] }.merge(options) |