Module: Recliner::Callbacks
- Extended by:
- ActiveSupport::Concern
- Includes:
- ActiveSupport::NewCallbacks
- Defined in:
- lib/recliner/callbacks.rb
Overview
Callbacks are hooks into the lifecycle of a Recliner object that allow 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 Document#save
call for a new document:
-
(-)
save
-
(-)
valid
-
(1)
before_validation
-
(-)
validate
-
(-)
validate_on_create
-
(2)
after_validation
-
(3)
before_save
-
(4)
before_create
-
(-)
create
-
(5)
after_create
-
(6)
after_save
That’s a total of eight callbacks, which gives you immense power to react and prepare for each state in the Recliner lifecycle. The sequence for calling Document#save
for an existing record is similar, except that each _on_create
callback is replaced by the corresponding _on_update
callback.
Examples:
class CreditCard < Recliner::Document
# 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 number?
end
end
class Subscription < Recliner::Document
before_create :record_signup
private
def record_signup
self.signed_up_on = Date.today
end
end
Inheritable callback queues
Besides the overwritable 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 < Recliner::Document
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
are called. Contrast this to the situation where we’ve implemented the save behavior through overwriteable methods:
class Topic < Recliner::Document
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 use the regular overwriteable methods when you want to leave it up to each descendant 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 < Recliner::Document
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 < Recliner::Document
before_save EncryptionWrapper.new
after_save EncryptionWrapper.new
after_initialize EncryptionWrapper.new
end
class EncryptionWrapper
def before_save(doc)
doc.credit_card_number = encrypt(doc.credit_card_number)
end
def after_save(doc)
doc.credit_card_number = decrypt(doc.credit_card_number)
end
alias_method :after_load, :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. You can make these callbacks more flexible by passing in other initialization data such as the name of the attribute to work with:
class BankAccount < Recliner::Document
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(doc)
doc.send("#{@attribute}=", encrypt(doc.send("#{@attribute}")))
end
def after_save(record)
doc.send("#{@attribute}=", decrypt(doc.send("#{@attribute}")))
end
alias_method :after_load, :after_save
private
def encrypt(value)
# Secrecy is committed
end
def decrypt(value)
# Secrecy is unveiled
end
end
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 < Recliner::Document
before_destroy 'self.class.delete_all "parent_id = #{id}"'
end
Notice that single quotes (‘) 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 < Recliner::Document
before_destroy 'self.class.delete_all "parent_id = #{id}"',
'puts "Evaluated after parents are destroyed"'
end
The after_load
and after_initialize
exceptions
Because after_load
and after_initialize
are called for each object found and instantiated by load/load!, we’ve had to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_load
and after_initialize
will only be run if an explicit implementation is defined (def after_load
). 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 Document#save
will return false
. If Document#save! is called it will raise a Recliner::RecordInvalid exception. Nothing will be appended to the errors object.
Canceling 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 collapse
- CALLBACKS =
[ :after_initialize, :after_load, :before_validation, :after_validation, :before_save, :around_save, :after_save, :before_create, :around_create, :after_create, :before_update, :around_update, :after_update, :before_destroy, :around_destroy, :after_destroy ]
Instance Method Summary collapse
-
#destroy_with_callbacks ⇒ Object
:nodoc:.
-
#valid_with_callbacks? ⇒ Boolean
:nodoc:.
Instance Method Details
#destroy_with_callbacks ⇒ Object
:nodoc:
290 291 292 293 294 |
# File 'lib/recliner/callbacks.rb', line 290 def destroy_with_callbacks #:nodoc: _run_destroy_callbacks do destroy_without_callbacks end end |
#valid_with_callbacks? ⇒ Boolean
:nodoc:
283 284 285 286 287 288 |
# File 'lib/recliner/callbacks.rb', line 283 def valid_with_callbacks? #:nodoc: @_on_validate = new_record? ? :create : :update _run_validation_callbacks do valid_without_callbacks? end end |