Module: CouchFoo::Callbacks

Defined in:
lib/couch_foo/callbacks.rb

Overview

Callbacks are hooks into the lifecycle of a Couch Foo 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 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 Couch Foo lifecycle.

Examples:

class CreditCard < CouchFoo::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 < CouchFoo::Base
  before_create :record_signup

  private
    def 
      self.signed_up_on = Date.today
    end
end

class Firm < CouchFoo::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 < CouchFoo::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 are called. Contrast this to the situation where we’ve implemented the save behavior through overwriteable methods:

class Topic < CouchFoo::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 use 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 < CouchFoo::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 < CouchFoo::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 < CouchFoo::Base
  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 < CouchFoo::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 RecordNotSaved 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.

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

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/couch_foo/callbacks.rb', line 184

def self.included(base) #:nodoc:
  base.extend Observable

  [:create_or_update, :valid?, :create, :update, :destroy].each do |method|
    base.send :alias_method_chain, method, :callbacks
  end

  base.send :include, ActiveSupport::Callbacks
  base.define_callbacks *CALLBACKS
end

Instance Method Details

#after_create ⇒ Object

Is called after Base.save on new objects that haven’t been saved yet (no record exists).



216
 
# File 'lib/couch_foo/callbacks.rb', line 216

def after_create() end

#after_destroy ⇒ Object

Is called after Base.destroy (and all the attributes have been frozen).

class Contact < CouchFoo::Base
  after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
end



285
 
# File 'lib/couch_foo/callbacks.rb', line 285

def after_destroy()  end

#after_save ⇒ Object

Is called after Base.save (regardless of whether it’s a create or update save).

class Contact < CouchFoo::Base
  after_save { logger.info( 'New contact saved!' ) }
end



203
 
# File 'lib/couch_foo/callbacks.rb', line 203

def after_save()  end

#after_update ⇒ Object

Is called after Base.save on existing objects that have a record.



229
 
# File 'lib/couch_foo/callbacks.rb', line 229

def after_update() end

#after_validation ⇒ Object

Is called after Validations.validate (which is part of the Base.save call).



243
 
# File 'lib/couch_foo/callbacks.rb', line 243

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).



251
 
# File 'lib/couch_foo/callbacks.rb', line 251

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 have a record.



259
 
# File 'lib/couch_foo/callbacks.rb', line 259

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).



213
 
# File 'lib/couch_foo/callbacks.rb', line 213

def before_create() end

#before_destroy ⇒ Object

Is called before Base.destroy.

Note: If you need to destroy or nullify associated records first, use the :dependent option on your associations.



278
 
# File 'lib/couch_foo/callbacks.rb', line 278

def before_destroy() end

#before_save ⇒ Object

Is called before Base.save (regardless of whether it’s a create or update save).



196
 
# File 'lib/couch_foo/callbacks.rb', line 196

def before_save() end

#before_update ⇒ Object

Is called before Base.save on existing objects that have a record.



226
 
# File 'lib/couch_foo/callbacks.rb', line 226

def before_update() end

#before_validation ⇒ Object

Is called before Validations.validate (which is part of the Base.save call).



240
 
# File 'lib/couch_foo/callbacks.rb', line 240

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).



247
 
# File 'lib/couch_foo/callbacks.rb', line 247

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 have a record.



255
 
# File 'lib/couch_foo/callbacks.rb', line 255

def before_validation_on_update() end

#destroy_with_callbacks ⇒ Object

:nodoc:



286
287
288
289
290
291
 
# File 'lib/couch_foo/callbacks.rb', line 286

def destroy_with_callbacks #:nodoc:
  return false if callback(:before_destroy) == false
  result = destroy_without_callbacks
  callback(:after_destroy)
  result
end

#valid_with_callbacks? ⇒ Boolean

:nodoc:

Returns:



261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/couch_foo/callbacks.rb', line 261

def valid_with_callbacks? #:nodoc:
  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