Skip to content
This repository
Browse code

Added some more text on Active Record callbacks

  • Loading branch information...
commit 490e02b17d26471e74bd9cbdc3ff368f88f6cccb 1 parent e95f541
Cássio Marques cassiomarques authored
137 railties/doc/guides/html/activerecord_validations_callbacks.html
@@ -282,7 +282,26 @@ <h2 id="site_title_tagline">Sustainable productivity for web-application develop
282 282 </ul>
283 283 </li>
284 284 <li>
285   - <a href="#_callbacks_that_get_triggered_when_an_objects_is_saved">Callbacks that get triggered when an objects is saved</a>
  285 + <a href="#_available_callbacks">Available callbacks</a>
  286 + <ul>
  287 +
  288 + <li><a href="#_callbacks_called_both_when_creating_or_updating_a_record">Callbacks called both when creating or updating a record.</a></li>
  289 +
  290 + <li><a href="#_callbacks_called_only_when_creating_a_new_record">Callbacks called only when creating a new record.</a></li>
  291 +
  292 + <li><a href="#_callbacks_called_only_when_updating_an_existing_record">Callbacks called only when updating an existing record.</a></li>
  293 +
  294 + <li><a href="#_callbacks_called_when_removing_a_record_from_the_database">Callbacks called when removing a record from the database.</a></li>
  295 +
  296 + <li><a href="#_the_tt_after_initialize_tt_and_tt_after_find_tt_callbacks">The <tt>after_initialize</tt> and <tt>after_find</tt> callbacks</a></li>
  297 +
  298 + </ul>
  299 + </li>
  300 + <li>
  301 + <a href="#_halting_execution">Halting Execution</a>
  302 + </li>
  303 + <li>
  304 + <a href="#_callback_classes_and_objects">Callback classes and objects</a>
286 305 </li>
287 306 <li>
288 307 <a href="#_changelog">Changelog</a>
@@ -376,7 +395,7 @@ <h3 id="_when_does_validation_happens">2.1. When does validation happens?</h3>
376 395 &gt;&gt; p.new_record?
377 396 =&gt; false</tt></pre>
378 397 </div></div>
379   -<div class="para"><p>Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either <tt>save</tt>, <tt>update_attribute</tt> or <tt>update_attributes</tt>) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.</p></div>
  398 +<div class="para"><p>Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either <tt>save</tt> or <tt>update_attributes</tt>) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.</p></div>
380 399 <div class="admonitionblock">
381 400 <table><tr>
382 401 <td class="icon">
@@ -952,17 +971,125 @@ <h3 id="_registering_callbacks_by_using_macro_style_class_methods">8.3. Register
952 971 </tr></table>
953 972 </div>
954 973 </div>
955   -<h2 id="_callbacks_that_get_triggered_when_an_objects_is_saved">9. Callbacks that get triggered when an objects is saved</h2>
  974 +<h2 id="_available_callbacks">9. Available callbacks</h2>
956 975 <div class="sectionbody">
  976 +<div class="para"><p>Here is a list with all the available Active Record callbacks, listed in the same order in which they will get called during the respective operations.</p></div>
  977 +<h3 id="_callbacks_called_both_when_creating_or_updating_a_record">9.1. Callbacks called both when creating or updating a record.</h3>
  978 +<div class="ilist"><ul>
  979 +<li>
  980 +<p>
  981 +<tt>before_validation</tt>
  982 +</p>
  983 +</li>
  984 +<li>
  985 +<p>
  986 +<tt>after_validation</tt>
  987 +</p>
  988 +</li>
  989 +<li>
  990 +<p>
  991 +<tt>before_save</tt>
  992 +</p>
  993 +</li>
  994 +<li>
  995 +<p>
  996 +<strong>INSERT OR UPDATE OPERATION</strong>
  997 +</p>
  998 +</li>
  999 +<li>
  1000 +<p>
  1001 +<tt>after_save</tt>
  1002 +</p>
  1003 +</li>
  1004 +</ul></div>
  1005 +<h3 id="_callbacks_called_only_when_creating_a_new_record">9.2. Callbacks called only when creating a new record.</h3>
  1006 +<div class="ilist"><ul>
  1007 +<li>
  1008 +<p>
  1009 +<tt>before_validation_on_create</tt>
  1010 +</p>
  1011 +</li>
  1012 +<li>
  1013 +<p>
  1014 +<tt>after_validation_on_create</tt>
  1015 +</p>
  1016 +</li>
  1017 +<li>
  1018 +<p>
  1019 +<tt>before_create</tt>
  1020 +</p>
  1021 +</li>
  1022 +<li>
  1023 +<p>
  1024 +<strong>INSERT OPERATION</strong>
  1025 +</p>
  1026 +</li>
  1027 +<li>
  1028 +<p>
  1029 +<tt>after_create</tt>
  1030 +</p>
  1031 +</li>
  1032 +</ul></div>
  1033 +<h3 id="_callbacks_called_only_when_updating_an_existing_record">9.3. Callbacks called only when updating an existing record.</h3>
957 1034 <div class="ilist"><ul>
958 1035 <li>
959 1036 <p>
960   -<tt>before_validation</tt> 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.
  1037 +<tt>before_validation_on_update</tt>
  1038 +</p>
  1039 +</li>
  1040 +<li>
  1041 +<p>
  1042 +<tt>after_validation_on_update</tt>
  1043 +</p>
  1044 +</li>
  1045 +<li>
  1046 +<p>
  1047 +<tt>before_update</tt>
  1048 +</p>
  1049 +</li>
  1050 +<li>
  1051 +<p>
  1052 +<strong>UPDATE OPERATION</strong>
  1053 +</p>
  1054 +</li>
  1055 +<li>
  1056 +<p>
  1057 +<tt>after_update</tt>
  1058 +</p>
  1059 +</li>
  1060 +</ul></div>
  1061 +<h3 id="_callbacks_called_when_removing_a_record_from_the_database">9.4. Callbacks called when removing a record from the database.</h3>
  1062 +<div class="ilist"><ul>
  1063 +<li>
  1064 +<p>
  1065 +<tt>before_destroy</tt>
  1066 +</p>
  1067 +</li>
  1068 +<li>
  1069 +<p>
  1070 +<strong>DELETE OPERATION</strong>
  1071 +</p>
  1072 +</li>
  1073 +<li>
  1074 +<p>
  1075 +<tt>after_destroy</tt>
961 1076 </p>
962 1077 </li>
963 1078 </ul></div>
  1079 +<div class="para"><p>The <tt>before_destroy</tt> and <tt>after_destroy</tt> callbacks will only be called if you delete the model using either the <tt>destroy</tt> instance method or one of the <tt>destroy</tt> or <tt>destroy_all</tt> class methods of your Active Record class. If you use <tt>delete</tt> or <tt>delete_all</tt> no callback operations will run, since Active Record will not instantiate any objects, accessing the records to be deleted directly in the database.</p></div>
  1080 +<h3 id="_the_tt_after_initialize_tt_and_tt_after_find_tt_callbacks">9.5. The <tt>after_initialize</tt> and <tt>after_find</tt> callbacks</h3>
  1081 +<div class="para"><p>The <tt>after_initialize</tt> callback will be called whenever an Active Record object is instantiated, either by direcly using <tt>new</tt> or when a record is loaded from the database. It can be useful to avoid the need to directly override your Active Record <tt>initialize</tt> method.</p></div>
  1082 +<div class="para"><p>The <tt>after_find</tt> callback will be called whenever Active Record loads a record from the database. When used together with <tt>after_initialize</tt> it will run first, since Active Record will first read the record from the database and them create the model object that will hold it.</p></div>
  1083 +<div class="para"><p>The <tt>after_initialize</tt> and <tt>after_find</tt> callbacks are a bit different from the others, since the only way to register those callbacks is by defining them as methods. If you try to register <tt>after_initialize</tt> or <tt>after_find</tt> using macro-style class methods, they will just be ignored. This behaviour is due to performance reasons, since <tt>after_initialize</tt> and <tt>after_find</tt> will both be called for each record found in the database, significantly slowing down the queries.</p></div>
  1084 +</div>
  1085 +<h2 id="_halting_execution">10. Halting Execution</h2>
  1086 +<div class="sectionbody">
  1087 +<div class="para"><p>As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model's validations, the registered callbacks and the database operation to be executed. However, if at any moment one of the callback methods returns a boolean <tt>false</tt> (not <tt>nil</tt>) value, this execution chain will be halted and the desired operation will not complete: your model will not get persisted in the database, or your records will not get deleted and so on.</p></div>
  1088 +</div>
  1089 +<h2 id="_callback_classes_and_objects">11. Callback classes and objects</h2>
  1090 +<div class="sectionbody">
964 1091 </div>
965   -<h2 id="_changelog">10. Changelog</h2>
  1092 +<h2 id="_changelog">12. Changelog</h2>
966 1093 <div class="sectionbody">
967 1094 <div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks">http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks</a></p></div>
968 1095 </div>
48 railties/doc/guides/source/activerecord_validations_callbacks.txt
@@ -47,7 +47,7 @@ We can see how it works by looking at the following script/console output:
47 47 => false
48 48 ------------------------------------------------------------------
49 49
50   -Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either +save+, +update_attribute+ or +update_attributes+) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.
  50 +Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either +save+ or +update_attributes+) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.
51 51
52 52 CAUTION: There are four methods that when called will trigger validation: +save+, +save!+, +update_attributes+ and +update_attributes!+. There is one method left, which is +update_attribute+. This method will update the value of an attribute without triggering any validation, so be careful when using +update_attribute+, since it can let you save your objects in an invalid state.
53 53
@@ -541,14 +541,56 @@ In Rails, the preferred way of registering callbacks is by using macro-style cla
541 541
542 542 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.
543 543
544   -== Callbacks that get triggered when an objects is saved
  544 +== Available callbacks
  545 +
  546 +Here is a list with all the available Active Record callbacks, listed in the same order in which they will get called during the respective operations.
545 547
546   -* +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.
  548 +=== Callbacks called both when creating or updating a record.
547 549
  550 +* +before_validation+
  551 +* +after_validation+
  552 +* +before_save+
  553 +* *INSERT OR UPDATE OPERATION*
  554 +* +after_save+
548 555
  556 +=== Callbacks called only when creating a new record.
549 557
  558 +* +before_validation_on_create+
  559 +* +after_validation_on_create+
  560 +* +before_create+
  561 +* *INSERT OPERATION*
  562 +* +after_create+
550 563
  564 +=== Callbacks called only when updating an existing record.
551 565
  566 +* +before_validation_on_update+
  567 +* +after_validation_on_update+
  568 +* +before_update+
  569 +* *UPDATE OPERATION*
  570 +* +after_update+
  571 +
  572 +=== Callbacks called when removing a record from the database.
  573 +
  574 +* +before_destroy+
  575 +* *DELETE OPERATION*
  576 +* +after_destroy+
  577 +
  578 +The +before_destroy+ and +after_destroy+ callbacks will only be called if you delete the model using either the +destroy+ instance method or one of the +destroy+ or +destroy_all+ class methods of your Active Record class. If you use +delete+ or +delete_all+ no callback operations will run, since Active Record will not instantiate any objects, accessing the records to be deleted directly in the database.
  579 +
  580 +=== The +after_initialize+ and +after_find+ callbacks
  581 +
  582 +The +after_initialize+ callback will be called whenever an Active Record object is instantiated, either by direcly using +new+ or when a record is loaded from the database. It can be useful to avoid the need to directly override your Active Record +initialize+ method.
  583 +
  584 +The +after_find+ callback will be called whenever Active Record loads a record from the database. When used together with +after_initialize+ it will run first, since Active Record will first read the record from the database and them create the model object that will hold it.
  585 +
  586 +The +after_initialize+ and +after_find+ callbacks are a bit different from the others, since the only way to register those callbacks is by defining them as methods. If you try to register +after_initialize+ or +after_find+ using macro-style class methods, they will just be ignored. This behaviour is due to performance reasons, since +after_initialize+ and +after_find+ will both be called for each record found in the database, significantly slowing down the queries.
  587 +
  588 +== Halting Execution
  589 +
  590 +As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model's validations, the registered callbacks and the database operation to be executed. However, if at any moment one of the callback methods returns a boolean +false+ (not +nil+) value, this execution chain will be halted and the desired operation will not complete: your model will not get persisted in the database, or your records will not get deleted and so on.
  591 +
  592 +
  593 +== Callback classes and objects
552 594
553 595
554 596

0 comments on commit 490e02b

Please sign in to comment.
Something went wrong with that request. Please try again.