Added :allow_blank to the common validation options section

2 files changed, 31 insertions, 2 deletions

diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html
index e8889da408..2aa09ee125 100644
--- a/railties/doc/guides/html/activerecord_validations_callbacks.html
+++ b/railties/doc/guides/html/activerecord_validations_callbacks.html
@@ -245,6 +245,8 @@ ul#navMain {
 						
 							<li><a href="#_the_tt_allow_nil_tt_option">The <tt>:allow_nil</tt> option</a></li>
 						
+							<li><a href="#_the_tt_allow_blank_tt_option">The <tt>:allow_blank</tt> option</a></li>
+						
 							<li><a href="#_the_tt_message_tt_option">The <tt>:message</tt> option</a></li>
 						
 							<li><a href="#_the_tt_on_tt_option">The <tt>:on</tt> option</a></li>
@@ -696,9 +698,22 @@ http://www.gnu.org/software/src-highlite -->
   validates_inclusion_of <span style="color: #990000">:</span>size<span style="color: #990000">,</span> <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">in</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #990000">%</span>w<span style="color: #990000">(</span>small medium large<span style="color: #990000">),</span>

     <span style="color: #990000">:</span>message <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"%s is not a valid size"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>allow_nil <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>

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

-<h3 id="_the_tt_message_tt_option">4.2. The <tt>:message</tt> option</h3>

+<h3 id="_the_tt_allow_blank_tt_option">4.2. The <tt>:allow_blank</tt> option</h3>

+<div class="paragraph"><p>In compliment to <tt>:allow_nil</tt> we have <tt>:allow_blank</tt>. This option will let validation pass if the attribute&#8217;s value is <tt>nil</tt> or an empty string, i.e., any value that returns <tt>true</tt> for <tt>blank?</tt>.</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> Topic <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base

+  validates_length_of <span style="color: #990000">:</span>title<span style="color: #990000">,</span> <span style="color: #990000">:</span>is <span style="color: #990000">=&gt;</span> <span style="color: #993399">5</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>allow_blank <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>

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

+

+Topic<span style="color: #990000">.</span>create<span style="color: #990000">(</span><span style="color: #FF0000">"title"</span> <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">""</span><span style="color: #990000">).</span>valid? <span style="font-style: italic"><span style="color: #9A1900"># =&gt; true</span></span>

+Topic<span style="color: #990000">.</span>create<span style="color: #990000">(</span><span style="color: #FF0000">"title"</span> <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span><span style="color: #990000">).</span>valid? <span style="font-style: italic"><span style="color: #9A1900"># =&gt; true</span></span></tt></pre></div></div>

+<h3 id="_the_tt_message_tt_option">4.3. The <tt>:message</tt> option</h3>

 <div class="paragraph"><p>As stated before, the <tt>:message</tt> option lets you specify the message that will be added to the <tt>errors</tt> collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper.</p></div>

-<h3 id="_the_tt_on_tt_option">4.3. The <tt>:on</tt> option</h3>

+<h3 id="_the_tt_on_tt_option">4.4. The <tt>:on</tt> option</h3>

 <div class="paragraph"><p>As stated before, the <tt>:on</tt> option lets you specify when the validation should happen. The default behaviour for all the built-in validation helpers is to be ran on save (both when you&#8217;re creating a new record and when you&#8217;re updating it). If you want to change it, you can use <tt>:on =&gt; :create</tt> to run the validation only when a new record is created or <tt>:on =&gt; :update</tt> to run the validation only when a record is updated.</p></div>

 <div class="listingblock">

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

diff --git a/railties/doc/guides/source/activerecord_validations_callbacks.txt b/railties/doc/guides/source/activerecord_validations_callbacks.txt
index 9865aeebb0..7d37df1ed2 100644
--- a/railties/doc/guides/source/activerecord_validations_callbacks.txt
+++ b/railties/doc/guides/source/activerecord_validations_callbacks.txt
@@ -317,6 +317,20 @@ class Coffee < ActiveRecord::Base
 end
 ------------------------------------------------------------------
 
+=== The +:allow_blank+ option
+
+In compliment to +:allow_nil+ we have +:allow_blank+. This option will let validation pass if the attribute's value is +nil+ or an empty string, i.e., any value that returns +true+ for +blank?+.
+
+[source, ruby]
+------------------------------------------------------------------
+class Topic < ActiveRecord::Base
+  validates_length_of :title, :is => 5, :allow_blank => true
+end
+
+Topic.create("title" => "").valid? # => true
+Topic.create("title" => nil).valid? # => true
+------------------------------------------------------------------
+
 === The +:message+ option
 
 As stated before, the +:message+ option lets you specify the message that will be added to the +errors+ collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper.