From c6e5ffbc5c5df14111d8925c82f143da73f6271b Mon Sep 17 00:00:00 2001 From: CassioMarques Date: Tue, 18 Nov 2008 22:10:02 -0200 Subject: Added some text about AR callbacks --- .../html/activerecord_validations_callbacks.html | 104 ++++++++++++++++++++- .../source/activerecord_validations_callbacks.txt | 73 +++++++++++++++ 2 files changed, 176 insertions(+), 1 deletion(-) diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html index 097ef706ca..4b860eeec0 100644 --- a/railties/doc/guides/html/activerecord_validations_callbacks.html +++ b/railties/doc/guides/html/activerecord_validations_callbacks.html @@ -270,6 +270,21 @@ ul#navMain { Using the errors collection
  • + Callbacks + +
    • +
  • + Callbacks that get triggered when an objects is saved +
    • +
  • Changelog
    • @@ -860,7 +875,94 @@ person.errors.< person.errors # => nil -

    8. Changelog

    +

    8. Callbacks

    +
    +

    Callbacks are methods that get called at certain moments of an object's lifecycle. With callbacks it's possible to write code that will run whenever an Active Record object is created, saved, updated, deleted or loaded from the database.

    +

    8.1. Callbacks registration

    +

    In order to use the available callbacks, you need to registrate them. There are two ways of doing that.

    +

    8.2. Registering callbacks by overriding the callback methods

    +

    You can specify the callback method direcly, by overriding it. Let's see how it works using the before_validation callback, which will surprisingly run right before any validation is done.

    +
    +
    +
    class User < ActiveRecord::Base
+  validates_presence_of :login, :email
+
+  protected
+  def before_validation
+    if self.login.nil?
+      self.login = email unless email.blank?
+    end
+  end
+end
+
    +

    8.3. Registering callbacks by using macro-style class methods

    +

    The other way you can register a callback method is by implementing it as an ordinary method, and then using a macro-style class method to register it as a callback. The last example could be written like that:

    +
    +
    +
    class User < ActiveRecord::Base
+  validates_presence_of :login, :email
+
+  before_validation :ensure_login_has_a_value
+
+  protected
+  def ensure_login_has_a_value
+    if self.login.nil?
+      self.login = email unless email.blank?
+    end
+  end
+end
+
    +

    The macro-style class methods can also receive a block. Rails best practices say that you should only use this style of registration if the code inside your block is so short that it fits in just one line.

    +
    +
    +
    class User < ActiveRecord::Base
+  validates_presence_of :login, :email
+
+  before_create {|user| user.name = user.login.capitalize if user.name.blank?}
+end
+
    +

    In Rails, the preferred way of registering callbacks is by using macro-style class methods. The main advantages of using macro-style class methods are:

    +
      +
    • +

      +You can add more than one method for each type of callback. Those methods will be queued for execution at the same order they were registered. +

      +
      • +
    • +

      +Readability, since your callback declarations will live at the beggining of your models' files. +

      +
      • +
    +
    + + + +
    +Caution +Remember to always declare the callback methods as being protected or private. These methods should never be public, otherwise it will be possible to call them from code outside the model, violating object encapsulation and exposing implementation details.
    +
    +
    +

    9. Callbacks that get triggered when an objects is saved

    +
    +
      +
    • +

      +before_validation will be triggered before any validation upon your object is done. You can use this callback to change the object's state so it becames valid. +

      +
      • +
    +
    +

    10. Changelog

    http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks

    diff --git a/railties/doc/guides/source/activerecord_validations_callbacks.txt b/railties/doc/guides/source/activerecord_validations_callbacks.txt index cbd914405e..a369a66bd3 100644 --- a/railties/doc/guides/source/activerecord_validations_callbacks.txt +++ b/railties/doc/guides/source/activerecord_validations_callbacks.txt @@ -477,6 +477,79 @@ person.errors.clear person.errors # => nil ------------------------------------------------------------------ +== Callbacks + +Callbacks are methods that get called at certain moments of an object's lifecycle. With callbacks it's possible to write code that will run whenever an Active Record object is created, saved, updated, deleted or loaded from the database. + +=== Callbacks registration + +In order to use the available callbacks, you need to registrate them. There are two ways of doing that. + +=== Registering callbacks by overriding the callback methods + +You can specify the callback method direcly, by overriding it. Let's see how it works using the +before_validation+ callback, which will surprisingly run right before any validation is done. + +[source, ruby] +------------------------------------------------------------------ +class User < ActiveRecord::Base + validates_presence_of :login, :email + + protected + def before_validation + if self.login.nil? + self.login = email unless email.blank? + end + end +end +------------------------------------------------------------------ + +=== Registering callbacks by using macro-style class methods + +The other way you can register a callback method is by implementing it as an ordinary method, and then using a macro-style class method to register it as a callback. The last example could be written like that: + +[source, ruby] +------------------------------------------------------------------ +class User < ActiveRecord::Base + validates_presence_of :login, :email + + before_validation :ensure_login_has_a_value + + protected + def ensure_login_has_a_value + if self.login.nil? + self.login = email unless email.blank? + end + end +end +------------------------------------------------------------------ + +The macro-style class methods can also receive a block. Rails best practices say that you should only use this style of registration if the code inside your block is so short that it fits in just one line. + +[source, ruby] +------------------------------------------------------------------ +class User < ActiveRecord::Base + validates_presence_of :login, :email + + before_create {|user| user.name = user.login.capitalize if user.name.blank?} +end +------------------------------------------------------------------ + +In Rails, the preferred way of registering callbacks is by using macro-style class methods. The main advantages of using macro-style class methods are: + +* You can add more than one method for each type of callback. Those methods will be queued for execution at the same order they were registered. +* Readability, since your callback declarations will live at the beggining of your models' files. + +CAUTION: Remember to always declare the callback methods as being protected or private. These methods should never be public, otherwise it will be possible to call them from code outside the model, violating object encapsulation and exposing implementation details. + +== Callbacks that get triggered when an objects is saved + +* +before_validation+ will be triggered before any validation upon your object is done. You can use this callback to change the object's state so it becames valid. + + + + + + == Changelog -- cgit v1.2.3