Module: ActiveRecord::Callbacks
- Defined in:
- lib/active_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
-
(4) after_validation
-
(5) after_validation_on_create
-
(6) before_save
-
(7) before_create
-
(-) create
-
(8) after_create
-
(9) after_save
That’s a total of nine callbacks, which gives you immense power to react and prepare for each state in the Active Record lifecyle.
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
# Automatically assign the signup date
def before_create
self.signed_up_on = Date.today
end
end
class Firm < ActiveRecord::Base
# Destroys the associated clients and people when the firm is destroyed
def before_destroy
Client.destroy_all "client_of = #{id}"
Person.destroy_all "firm_id = #{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.
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 is some times 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_initialize, :after_save
private
def encrypt(value)
# Secrecy is committed
end
def decrypt(value)
# Secrecy is unvieled
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 is called for each object instantiated found 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 can only be declared using an explicit implementation. So using the inheritable callback queue for after_find and after_initialize won’t work.
Defined Under Namespace
Modules: ClassMethods
Constant Summary collapse
- 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 collapse
-
.append_features(base) ⇒ Object
:nodoc:.
Instance Method Summary collapse
-
#after_create ⇒ Object
Is called after Base.save on new objects that haven’t been saved yet (no record exists).
-
#after_destroy ⇒ Object
Is called after Base.destroy (and all the attributes have been frozen).
-
#after_save ⇒ Object
Is called after Base.save (regardless of whether it’s a create or update save).
-
#after_update ⇒ Object
Is called after Base.save on existing objects that has a record.
-
#after_validation ⇒ Object
Is called after Validations.validate (which is part of the Base.save call).
-
#after_validation_on_create ⇒ Object
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).
-
#after_validation_on_update ⇒ Object
Is called after Validations.validate (which is part of the Base.save call) on existing objects that has a record.
-
#before_create ⇒ Object
Is called before Base.save on new objects that haven’t been saved yet (no record exists).
-
#before_destroy ⇒ Object
Is called before Base.destroy.
-
#before_save ⇒ Object
Is called before Base.save (regardless of whether it’s a create or update save).
-
#before_update ⇒ Object
Is called before Base.save on existing objects that has a record.
-
#before_validation ⇒ Object
Is called before Validations.validate (which is part of the Base.save call).
-
#before_validation_on_create ⇒ Object
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).
-
#before_validation_on_update ⇒ Object
Is called before Validations.validate (which is part of the Base.save call) on existing objects that has a record.
-
#callback(callback_method) ⇒ Object
:nodoc:.
-
#create_or_update_with_callbacks ⇒ Object
:nodoc:.
-
#create_with_callbacks ⇒ Object
:nodoc:.
-
#destroy_with_callbacks ⇒ Object
:nodoc:.
- #filter_block?(filter) ⇒ Boolean
- #filter_class?(filter, callback_method) ⇒ Boolean
-
#initialize_with_callbacks(attributes = nil) {|_self| ... } ⇒ Object
Is called after the object has been instantiated by a call to Base.new.
-
#notify(callback_method) ⇒ Object
:nodoc:.
- #run_callbacks(callback_method) ⇒ Object
-
#update_with_callbacks ⇒ Object
:nodoc:.
-
#valid_with_callbacks ⇒ Object
:nodoc:.
Class Method Details
.append_features(base) ⇒ Object
:nodoc:
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 |
# File 'lib/active_record/callbacks.rb', line 162 def self.append_features(base) #:nodoc: super base.extend(ClassMethods) base.class_eval do class << self include Observable alias_method :instantiate_without_callbacks, :instantiate alias_method :instantiate, :instantiate_with_callbacks end end base.class_eval do alias_method :initialize_without_callbacks, :initialize alias_method :initialize, :initialize_with_callbacks alias_method :create_or_update_without_callbacks, :create_or_update alias_method :create_or_update, :create_or_update_with_callbacks alias_method :valid_without_callbacks, :valid? alias_method :valid?, :valid_with_callbacks alias_method :create_without_callbacks, :create alias_method :create, :create_with_callbacks alias_method :update_without_callbacks, :update alias_method :update, :update_with_callbacks alias_method :destroy_without_callbacks, :destroy alias_method :destroy, :destroy_with_callbacks end CALLBACKS.each { |cb| base.class_eval("def self.#{cb}(*methods) write_inheritable_array(\"#{cb}\", methods) end") } end |
Instance Method Details
#after_create ⇒ Object
Is called after Base.save on new objects that haven’t been saved yet (no record exists).
232 |
# File 'lib/active_record/callbacks.rb', line 232 def after_create() end |
#after_destroy ⇒ Object
Is called after Base.destroy (and all the attributes have been frozen).
289 |
# File 'lib/active_record/callbacks.rb', line 289 def after_destroy() end |
#after_save ⇒ Object
Is called after Base.save (regardless of whether it’s a create or update save).
221 |
# File 'lib/active_record/callbacks.rb', line 221 def after_save() end |
#after_update ⇒ Object
Is called after Base.save on existing objects that has a record.
243 |
# File 'lib/active_record/callbacks.rb', line 243 def after_update() end |
#after_validation ⇒ Object
Is called after Validations.validate (which is part of the Base.save call).
255 |
# File 'lib/active_record/callbacks.rb', line 255 def after_validation() end |
#after_validation_on_create ⇒ Object
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).
263 |
# File 'lib/active_record/callbacks.rb', line 263 def after_validation_on_create() end |
#after_validation_on_update ⇒ Object
Is called after Validations.validate (which is part of the Base.save call) on existing objects that has a record.
271 |
# File 'lib/active_record/callbacks.rb', line 271 def after_validation_on_update() end |
#before_create ⇒ Object
Is called before Base.save on new objects that haven’t been saved yet (no record exists).
229 |
# File 'lib/active_record/callbacks.rb', line 229 def before_create() end |
#before_destroy ⇒ Object
Is called before Base.destroy.
286 |
# File 'lib/active_record/callbacks.rb', line 286 def before_destroy() end |
#before_save ⇒ Object
Is called before Base.save (regardless of whether it’s a create or update save).
218 |
# File 'lib/active_record/callbacks.rb', line 218 def before_save() end |
#before_update ⇒ Object
Is called before Base.save on existing objects that has a record.
240 |
# File 'lib/active_record/callbacks.rb', line 240 def before_update() end |
#before_validation ⇒ Object
Is called before Validations.validate (which is part of the Base.save call).
252 |
# File 'lib/active_record/callbacks.rb', line 252 def before_validation() end |
#before_validation_on_create ⇒ Object
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).
259 |
# File 'lib/active_record/callbacks.rb', line 259 def before_validation_on_create() end |
#before_validation_on_update ⇒ Object
Is called before Validations.validate (which is part of the Base.save call) on existing objects that has a record.
267 |
# File 'lib/active_record/callbacks.rb', line 267 def before_validation_on_update() end |
#callback(callback_method) ⇒ Object
:nodoc:
296 297 298 299 300 |
# File 'lib/active_record/callbacks.rb', line 296 def callback(callback_method) #:nodoc: run_callbacks(callback_method) send(callback_method) notify(callback_method) end |
#create_or_update_with_callbacks ⇒ Object
:nodoc:
222 223 224 225 226 |
# File 'lib/active_record/callbacks.rb', line 222 def create_or_update_with_callbacks #:nodoc: callback(:before_save) create_or_update_without_callbacks callback(:after_save) end |
#create_with_callbacks ⇒ Object
:nodoc:
233 234 235 236 237 |
# File 'lib/active_record/callbacks.rb', line 233 def create_with_callbacks #:nodoc: callback(:before_create) create_without_callbacks callback(:after_create) end |
#destroy_with_callbacks ⇒ Object
:nodoc:
290 291 292 293 294 |
# File 'lib/active_record/callbacks.rb', line 290 def destroy_with_callbacks #:nodoc: callback(:before_destroy) destroy_without_callbacks callback(:after_destroy) end |
#filter_block?(filter) ⇒ Boolean
324 325 326 |
# File 'lib/active_record/callbacks.rb', line 324 def filter_block?(filter) filter.respond_to?("call") && (filter.arity == 1 || filter.arity == -1) end |
#filter_class?(filter, callback_method) ⇒ Boolean
328 329 330 |
# File 'lib/active_record/callbacks.rb', line 328 def filter_class?(filter, callback_method) filter.respond_to?(callback_method) end |
#initialize_with_callbacks(attributes = nil) {|_self| ... } ⇒ Object
Is called after the object has been instantiated by a call to Base.new. def after_initialize() end
211 212 213 214 215 |
# File 'lib/active_record/callbacks.rb', line 211 def initialize_with_callbacks(attributes = nil) #:nodoc: initialize_without_callbacks(attributes) yield self if block_given? after_initialize if respond_to_without_attributes?(:after_initialize) end |
#notify(callback_method) ⇒ Object
:nodoc:
332 333 334 335 |
# File 'lib/active_record/callbacks.rb', line 332 def notify(callback_method) #:nodoc: self.class.changed self.class.notify_observers(callback_method, self) end |
#run_callbacks(callback_method) ⇒ Object
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 |
# File 'lib/active_record/callbacks.rb', line 302 def run_callbacks(callback_method) filters = self.class.read_inheritable_attribute(callback_method.to_s) if filters.nil? then return end filters.each do |filter| if Symbol === filter self.send(filter) elsif String === filter eval(filter, binding) elsif filter_block?(filter) filter.call(self) elsif filter_class?(filter, callback_method) filter.send(callback_method, self) else raise( ActiveRecordError, "Filters need to be either a symbol, string (to be eval'ed), proc/method, or " + "class implementing a static filter method" ) end end end |
#update_with_callbacks ⇒ Object
:nodoc:
245 246 247 248 249 |
# File 'lib/active_record/callbacks.rb', line 245 def update_with_callbacks #:nodoc: callback(:before_update) update_without_callbacks callback(:after_update) end |
#valid_with_callbacks ⇒ Object
:nodoc:
273 274 275 276 277 278 279 280 281 282 283 |
# File 'lib/active_record/callbacks.rb', line 273 def valid_with_callbacks #:nodoc: callback(:before_validation) if new_record? then callback(:before_validation_on_create) else callback(:before_validation_on_update) end 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 |