Module: BigRecord::Callbacks
- Defined in:
- lib/big_record/callbacks.rb
Overview
Callbacks are hooks into the lifecycle of an Active Record object that allows you to trigger logic before or after an alteration of the object state. This can be used to make sure that associated and dependent objects are deleted when destroy is called (by overwriting before_destroy) or to massage attributes before they’re validated (by overwriting before_validation). As an example of the callbacks initiated, consider the Base#save call:
- (-) save
- (-) valid?
- (1) before_validation
- (2) before_validation_on_create
- (-) validate
- (-) validate_on_create
- (3) after_validation
- (4) after_validation_on_create
- (5) before_save
- (6) before_create
- (-) create
- (7) after_create
- (8) after_save
That’s a total of eight callbacks, which gives you immense power to react and prepare for each state in the Active Record lifecycle.
Examples:
class CreditCard < ActiveRecord::Base # Strip everything but digits, so the user can specify "555 234 34" or # "5552-3434" or both will mean "55523434" def before_validation_on_create self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number") end end class Subscription < ActiveRecord::Base before_create :record_signup private def record_signup self.signed_up_on = Date.today end end class Firm < ActiveRecord::Base # Destroys the associated clients and people when the firm is destroyed before_destroy { |record| Person.destroy_all "firm_id = #{record.id}" } before_destroy { |record| Client.destroy_all "client_of = #{record.id}" } end
Inheritable callback queues
Besides the overwriteable callback methods, it’s also possible to register callbacks through the use of the callback macros. Their main advantage is that the macros add behavior into a callback queue that is kept intact down through an inheritance hierarchy. Example:
class Topic < ActiveRecord::Base before_destroy :destroy_author end class Reply < Topic before_destroy :destroy_readers end
Now, when Topic#destroy is run only destroy_author is called. When Reply#destroy is run both destroy_author and destroy_readers is called. Contrast this to the situation where we’ve implemented the save behavior through overwriteable methods:
class Topic < ActiveRecord::Base def before_destroy() end end class Reply < Topic def before_destroy() destroy_readers end end
In that case, Reply#destroy would only run destroy_readers and not destroy_author. So use the callback macros when you want to ensure that a certain callback is called for the entire hierarchy and the regular overwriteable methods when you want to leave it up to each descendent to decide whether they want to call super and trigger the inherited callbacks.
*IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the callbacks before specifying the associations. Otherwise, you might trigger the loading of a child before the parent has registered the callbacks and they won’t be inherited.
Types of callbacks
There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects, inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for creating mix-ins), and inline eval methods are deprecated.
The method reference callbacks work by specifying a protected or private method available in the object, like this:
class Topic < ActiveRecord::Base before_destroy :delete_parents private def delete_parents self.class.delete_all "parent_id = #{id}" end end
The callback objects have methods named after the callback called with the record as the only parameter, such as:
class BankAccount < ActiveRecord::Base before_save EncryptionWrapper.new("credit_card_number") after_save EncryptionWrapper.new("credit_card_number") after_initialize EncryptionWrapper.new("credit_card_number") end class EncryptionWrapper def initialize(attribute) @attribute = attribute end def before_save(record) record.credit_card_number = encrypt(record.credit_card_number) end def after_save(record) record.credit_card_number = decrypt(record.credit_card_number) end alias_method :after_find, :after_save private def encrypt(value) # Secrecy is committed end def decrypt(value) # Secrecy is unveiled end end
So you specify the object you want messaged on a given callback. When that callback is triggered, the object has a method by the name of the callback messaged.
The callback macros usually accept a symbol for the method they’re supposed to run, but you can also pass a "method string", which will then be evaluated within the binding of the callback. Example:
class Topic < ActiveRecord::Base before_destroy 'self.class.delete_all "parent_id = #{id}"' end
Notice that single plings (’) are used so the #id part isn’t evaluated until the callback is triggered. Also note that these inline callbacks can be stacked just like the regular ones:
class Topic < ActiveRecord::Base before_destroy 'self.class.delete_all "parent_id = #{id}"', 'puts "Evaluated after parents are destroyed"' end
The after_find and after_initialize exceptions
Because after_find and after_initialize are called for each object found and instantiated by a finder, such as Base.find(:all), we’ve had to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_find and after_initialize will only be run if an explicit implementation is defined (def after_find). In that case, all of the callback types will be called.
before_validation* returning statements
If the returning value of a before_validation callback can be evaluated to false, the process will be aborted and Base#save will return false. If Base#save! is called it will raise a RecordNotSave error. Nothing will be appended to the errors object.
Cancelling callbacks
If a before_* callback returns false, all the later callbacks and the associated action are cancelled. If an after_* callback returns false, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks defined as methods on the model, which are called last.
Defined Under Namespace
Modules: ClassMethods
Constant Summary
- CALLBACKS =
%w( after_find after_initialize before_save after_save before_create after_create before_update after_update before_validation after_validation before_validation_on_create after_validation_on_create before_validation_on_update after_validation_on_update before_destroy after_destroy )
Class Method Summary
-
+ (Object) included(base)
:nodoc:.
Instance Method Summary
-
- (Object) after_create
Is called after Base.save on new objects that haven’t been saved yet (no record exists).
-
- (Object) after_destroy
Is called after Base.destroy (and all the attributes have been frozen).
-
- (Object) after_save
Is called after Base.save (regardless of whether it’s a create or update save).
-
- (Object) after_update
Is called after Base.save on existing objects that have a record.
-
- (Object) after_validation
Is called after Validations.validate (which is part of the Base.save call).
-
- (Object) after_validation_on_create
Is called after Validations.validate (which is part of the Base.save call) on new objects that haven’t been saved yet (no record exists).
-
- (Object) after_validation_on_update
Is called after Validations.validate (which is part of the Base.save call) on existing objects that have a record.
-
- (Object) before_create
Is called before Base.save on new objects that haven’t been saved yet (no record exists).
-
- (Object) before_destroy
Is called before Base.destroy.
-
- (Object) before_save
Is called before Base.save (regardless of whether it’s a create or update save).
-
- (Object) before_update
Is called before Base.save on existing objects that have a record.
-
- (Object) before_validation
Is called before Validations.validate (which is part of the Base.save call).
-
- (Object) before_validation_on_create
Is called before Validations.validate (which is part of the Base.save call) on new objects that haven’t been saved yet (no record exists).
-
- (Object) before_validation_on_update
Is called before Validations.validate (which is part of the Base.save call) on existing objects that have a record.
-
- (Object) create_or_update_with_callbacks
:nodoc:.
-
- (Object) create_with_callbacks
:nodoc:.
-
- (Object) destroy_with_callbacks
:nodoc:.
-
- (Object) initialize_with_callbacks(attributes = nil)
Is called after the object has been instantiated by a call to Base.new.
-
- (Object) update_with_callbacks
:nodoc:.
-
- (Boolean) valid_with_callbacks?
:nodoc:.
Class Method Details
+ (Object) included(base)
:nodoc:
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 |
# File 'lib/big_record/callbacks.rb', line 179 def self.included(base) #:nodoc: base.extend(ClassMethods) base.class_eval do class << self include Observable alias_method_chain :instantiate, :callbacks end [:initialize, :create_or_update, :valid?, :create, :update, :destroy].each do |method| alias_method_chain method, :callbacks end end CALLBACKS.each do |method| base.class_eval "def self.\#{method}(*callbacks, &block)\ncallbacks << block if block_given?\nwrite_inheritable_array(\#{method.to_sym.inspect}, callbacks)\nend\n" end end |
Instance Method Details
- (Object) after_create
Is called after Base.save on new objects that haven’t been saved yet (no record exists).
252 |
# File 'lib/big_record/callbacks.rb', line 252 def after_create() end |
- (Object) after_destroy
Is called after Base.destroy (and all the attributes have been frozen).
class Contact < ActiveRecord::Base after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) } end
319 |
# File 'lib/big_record/callbacks.rb', line 319 def after_destroy() end |
- (Object) after_save
Is called after Base.save (regardless of whether it’s a create or update save).
class Contact < ActiveRecord::Base after_save { logger.info( 'New contact saved!' ) } end
240 |
# File 'lib/big_record/callbacks.rb', line 240 def after_save() end |
- (Object) after_update
Is called after Base.save on existing objects that have a record.
264 |
# File 'lib/big_record/callbacks.rb', line 264 def after_update() end |
- (Object) after_validation
Is called after Validations.validate (which is part of the Base.save call).
277 |
# File 'lib/big_record/callbacks.rb', line 277 def after_validation() end |
- (Object) after_validation_on_create
Is called after Validations.validate (which is part of the Base.save call) on new objects that haven’t been saved yet (no record exists).
285 |
# File 'lib/big_record/callbacks.rb', line 285 def after_validation_on_create() end |
- (Object) after_validation_on_update
Is called after Validations.validate (which is part of the Base.save call) on existing objects that have a record.
293 |
# File 'lib/big_record/callbacks.rb', line 293 def after_validation_on_update() end |
- (Object) before_create
Is called before Base.save on new objects that haven’t been saved yet (no record exists).
249 |
# File 'lib/big_record/callbacks.rb', line 249 def before_create() end |
- (Object) before_destroy
Is called before Base.destroy.
Note: If you need to destroy or nullify associated records first, use the _:dependent_ option on your associations.
312 |
# File 'lib/big_record/callbacks.rb', line 312 def before_destroy() end |
- (Object) before_save
Is called before Base.save (regardless of whether it’s a create or update save).
233 |
# File 'lib/big_record/callbacks.rb', line 233 def before_save() end |
- (Object) before_update
Is called before Base.save on existing objects that have a record.
261 |
# File 'lib/big_record/callbacks.rb', line 261 def before_update() end |
- (Object) before_validation
Is called before Validations.validate (which is part of the Base.save call).
274 |
# File 'lib/big_record/callbacks.rb', line 274 def before_validation() end |
- (Object) before_validation_on_create
Is called before Validations.validate (which is part of the Base.save call) on new objects that haven’t been saved yet (no record exists).
281 |
# File 'lib/big_record/callbacks.rb', line 281 def before_validation_on_create() end |
- (Object) before_validation_on_update
Is called before Validations.validate (which is part of the Base.save call) on existing objects that have a record.
289 |
# File 'lib/big_record/callbacks.rb', line 289 def before_validation_on_update() end |
- (Object) create_or_update_with_callbacks
:nodoc:
241 242 243 244 245 246 |
# File 'lib/big_record/callbacks.rb', line 241 def create_or_update_with_callbacks return false if callback(:before_save) == false result = create_or_update_without_callbacks callback(:after_save) result end |
- (Object) create_with_callbacks
:nodoc:
253 254 255 256 257 258 |
# File 'lib/big_record/callbacks.rb', line 253 def create_with_callbacks return false if callback(:before_create) == false result = create_without_callbacks callback(:after_create) result end |
- (Object) destroy_with_callbacks
:nodoc:
320 321 322 323 324 325 |
# File 'lib/big_record/callbacks.rb', line 320 def destroy_with_callbacks return false if callback(:before_destroy) == false result = destroy_without_callbacks callback(:after_destroy) result end |
- (Object) initialize_with_callbacks(attributes = nil)
Is called after the object has been instantiated by a call to Base.new. def after_initialize() end
225 226 227 228 229 230 |
# File 'lib/big_record/callbacks.rb', line 225 def initialize_with_callbacks(attributes = nil) #:nodoc: initialize_without_callbacks(attributes) result = yield self if block_given? callback(:after_initialize) if respond_to_without_attributes?(:after_initialize) result end |
- (Object) update_with_callbacks
:nodoc:
266 267 268 269 270 271 |
# File 'lib/big_record/callbacks.rb', line 266 def update_with_callbacks return false if callback(:before_update) == false result = update_without_callbacks callback(:after_update) result end |
- (Boolean) valid_with_callbacks?
:nodoc:
295 296 297 298 299 300 301 302 303 304 305 306 |
# File 'lib/big_record/callbacks.rb', line 295 def valid_with_callbacks? return false if callback(:before_validation) == false if new_record? then result = callback(:before_validation_on_create) else result = callback(:before_validation_on_update) end return false if result == false result = valid_without_callbacks? callback(:after_validation) if new_record? then callback(:after_validation_on_create) else callback(:after_validation_on_update) end return result end |