module BigRecord::Callbacks
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 BigRecord::Base#save call:
-
(-) save
-
(-) valid?
-
(-) validate
-
(-) validate_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() destroy_author 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 BigRecord::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 BigRecord::Base#save will return false. If BigRecord::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.
Constants
- CALLBACKS
Public Instance Methods
Is called after BigRecord::Base#save on new objects that haven't been saved yet (no record exists).
# File lib/big_record/callbacks.rb, line 251 def after_create() end
Is called after BigRecord::Base#destroy (and all the attributes have been frozen).
class Contact < ActiveRecord::Base after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) } end
# File lib/big_record/callbacks.rb, line 318 def after_destroy() end
Is called after BigRecord::Base#save (regardless of whether it's a create or update save).
class Contact < ActiveRecord::Base after_save { logger.info( 'New contact saved!' ) } end
# File lib/big_record/callbacks.rb, line 239 def after_save() end
Is called after BigRecord::Base#save on existing objects that have a record.
# File lib/big_record/callbacks.rb, line 263 def after_update() end
Is called after BigRecord::Validations#validate (which is part of the BigRecord::Base#save call).
# File lib/big_record/callbacks.rb, line 276 def after_validation() end
Is called after BigRecord::Validations#validate (which is part of the BigRecord::Base#save call) on new objects that haven't been saved yet (no record exists).
# File lib/big_record/callbacks.rb, line 284 def after_validation_on_create() end
Is called after BigRecord::Validations#validate (which is part of the BigRecord::Base#save call) on existing objects that have a record.
# File lib/big_record/callbacks.rb, line 292 def after_validation_on_update() end
Is called before BigRecord::Base#save on new objects that haven't been saved yet (no record exists).
# File lib/big_record/callbacks.rb, line 248 def before_create() end
Is called before BigRecord::Base#destroy.
Note: If you need to destroy or nullify associated records first, use the :dependent option on your associations.
# File lib/big_record/callbacks.rb, line 311 def before_destroy() end
Is called before BigRecord::Base#save (regardless of whether it's a create or update save).
# File lib/big_record/callbacks.rb, line 232 def before_save() end
Is called before BigRecord::Base#save on existing objects that have a record.
# File lib/big_record/callbacks.rb, line 260 def before_update() end
Is called before BigRecord::Validations#validate (which is part of the BigRecord::Base#save call).
# File lib/big_record/callbacks.rb, line 273 def before_validation() end
Is called before BigRecord::Validations#validate (which is part of the BigRecord::Base#save call) on new objects that haven't been saved yet (no record exists).
# File lib/big_record/callbacks.rb, line 280 def before_validation_on_create() end
Is called before BigRecord::Validations#validate (which is part of the BigRecord::Base#save call) on existing objects that have a record.
# File lib/big_record/callbacks.rb, line 288 def before_validation_on_update() end
Private Instance Methods
# File lib/big_record/callbacks.rb, line 327 def callback(method) notify(method) callbacks_for(method).each do |callback| result = case callback when Symbol self.send(callback) when String eval(callback, binding) when Proc, Method callback.call(self) else if callback.respond_to?(method) callback.send(method, self) else raise ActiveRecordError, "Callbacks must be a symbol denoting the method to call, a string to be evaluated, a block to be invoked, or an object responding to the callback method." end end return false if (result.is_a?FalseClass) end result = send(method) if respond_to_without_attributes?(method) return result end
# File lib/big_record/callbacks.rb, line 353 def callbacks_for(method) self.class.read_inheritable_attribute(method.to_sym) or [] end
# File lib/big_record/callbacks.rb, line 357 def invoke_and_notify(method) notify(method) send(method) if respond_to_without_attributes?(method) end