Added documentation for validates_uniqueness_of

2 files changed, 66 insertions, 3 deletions

diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html
index 7149ee5f90..a85a4db5d8 100644
--- a/railties/doc/guides/html/activerecord_validations_callbacks.html
+++ b/railties/doc/guides/html/activerecord_validations_callbacks.html
@@ -235,7 +235,7 @@ ul#navMain {
 						
 							<li><a href="#_the_tt_validates_presence_of_tt_helper">The <tt>validates_presence_of</tt> helper</a></li>
 						
-							<li><a href="#_the_validates_uniqueness_of_helper">The validates_uniqueness_of+ helper</a></li>
+							<li><a href="#_the_tt_validates_uniqueness_of_tt_helper">The <tt>validates_uniqueness_of</tt> helper</a></li>
 						
 						</ul>
 					</li>
@@ -575,7 +575,39 @@ http://www.gnu.org/software/src-highlite -->
 </tr></table>

 </div>

 <div class="para"><p>The default error message for <tt>validates_presence_of</tt> is "<em>can't be empty</em>".</p></div>

-<h3 id="_the_validates_uniqueness_of_helper">3.11. The validates_uniqueness_of+ helper</h3>

+<h3 id="_the_tt_validates_uniqueness_of_tt_helper">3.11. The <tt>validates_uniqueness_of</tt> helper</h3>

+<div class="para"><p>This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your database, so it may happen that two different database connections create two records with the same value for a column that you wish were unique. To avoid that, you must create an unique index in your database.</p></div>

+<div class="listingblock">

+<div class="content"><!-- Generator: GNU source-highlight 2.9

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite -->

+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Account <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base

+  validates_uniqueness_of <span style="color: #990000">:</span>email

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+</tt></pre></div></div>

+<div class="para"><p>The validation happens by performing a SQL query into the model's table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.</p></div>

+<div class="para"><p>There is a <tt>:scope</tt> option that you can use to specify other attributes that must be used to define uniqueness:</p></div>

+<div class="listingblock">

+<div class="content"><!-- Generator: GNU source-highlight 2.9

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite -->

+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Holiday <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base

+  validates_uniqueness_of <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>scope <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>year<span style="color: #990000">,</span> <span style="color: #990000">:</span>message <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"Should happen once per year"</span>

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+</tt></pre></div></div>

+<div class="para"><p>There is also a <tt>:case_sensitive</tt> option that you can use to define if the uniqueness contraint will be case sensitive or not. This option defaults to true.</p></div>

+<div class="listingblock">

+<div class="content"><!-- Generator: GNU source-highlight 2.9

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite -->

+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Person <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base

+  validates_uniqueness_of <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>case_sensitive <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+</tt></pre></div></div>

+<div class="para"><p>The default error message for <tt>validates_uniqueness_of</tt> is "<em>has already been taken</em>".</p></div>

 </div>

 <h2 id="_common_validation_options">4. Common validation options</h2>

 <div class="sectionbody">

diff --git a/railties/doc/guides/source/activerecord_validations_callbacks.txt b/railties/doc/guides/source/activerecord_validations_callbacks.txt
index 04248d592f..bea0cf425b 100644
--- a/railties/doc/guides/source/activerecord_validations_callbacks.txt
+++ b/railties/doc/guides/source/activerecord_validations_callbacks.txt
@@ -262,7 +262,38 @@ NOTE: If you want to validate the presence of a boolean field (where the real va
 
 The default error message for +validates_presence_of+ is "_can't be empty_".
 
-=== The validates_uniqueness_of+ helper
+=== The +validates_uniqueness_of+ helper
+
+This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your database, so it may happen that two different database connections create two records with the same value for a column that you wish were unique. To avoid that, you must create an unique index in your database.
+
+[source, ruby]
+------------------------------------------------------------------
+class Account < ActiveRecord::Base
+  validates_uniqueness_of :email
+end
+------------------------------------------------------------------
+
+The validation happens by performing a SQL query into the model's table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.
+
+There is a +:scope+ option that you can use to specify other attributes that must be used to define uniqueness:
+
+[source, ruby]
+------------------------------------------------------------------
+class Holiday < ActiveRecord::Base
+  validates_uniqueness_of :name, :scope => :year, :message => "Should happen once per year"
+end
+------------------------------------------------------------------
+
+There is also a +:case_sensitive+ option that you can use to define if the uniqueness contraint will be case sensitive or not. This option defaults to true.
+
+[source, ruby]
+------------------------------------------------------------------
+class Person < ActiveRecord::Base
+  validates_uniqueness_of :name, :case_sensitive => false
+end
+------------------------------------------------------------------
+
+The default error message for +validates_uniqueness_of+ is "_has already been taken_".
 
 == Common validation options