Merge changes to Active Record Validations section

4 files changed, 53 insertions, 35 deletions

diff --git a/railties/guides/source/activerecord_validations_callbacks.textile b/railties/guides/source/activerecord_validations_callbacks.textile
index 4dc41659e3..f7669e8977 100644
--- a/railties/guides/source/activerecord_validations_callbacks.textile
+++ b/railties/guides/source/activerecord_validations_callbacks.textile
@@ -55,33 +55,39 @@ CAUTION: There are many ways to change the state of an object in the database. S
 
 The following methods trigger validations, and will save the object to the database only if the object is valid. The bang versions (e.g. +save!+) will raise an exception if the record is invalid. The non-bang versions (e.g. +save+) simply return +false+.
 
-* "+create+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002214 
-* "+create!+":http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html#M002116
-* "+save+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002274
-* "+save!+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002275
-* "+update+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002215
-* "+update_attributes+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002281
-* "+update_attributes!+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002282
-
-The following methods bypass validations, and will save the object to the database regardless of its validity. They should be used with caution:
-
-* "+decrement!+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002286
-* "+decrement_counter+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002224
-* "+increment!+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002284
-* "+increment_counter+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002223
-* "+toggle!+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002288
-* "+update_all+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002218
-* "+update_attribute+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002280
-* "+update_counters+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002222
-
-Note that +save+ also has the ability to bypass validations if passed +false+. This technique should be used with caution: 
+* +create+
+* +create!+
+* +save+
+* +save!+
+* +update+
+* +update_attributes+
+* +update_attributes!+
+
+The following methods skip validations, and will save the object to the database regardless of its validity. They should be used with caution:
+
+* +decrement!+
+* +decrement_counter+
+* +increment!+
+* +increment_counter+
+* +toggle!+
+* +update_all+
+* +update_attribute+
+* +update_counters+
+
+Note that +save+ also has the ability to skip validations if passed +false+. This technique should be used with caution: 
 
 * "+save(false)+":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002274
 
+h4. Skipping Validations
+
+TODO: Probably move the list above and mention save(false). Also mention that save(false) doesn't only skip the validations, but a lots of other callbacks too.
+
 h4. Object#valid?
 
 To verify whether an object is valid, Active Record uses the +valid?+ method, which basically looks inside the object to see if it has any validation errors. These errors live in a collection that can be accessed through the +errors+ instance method. The process is really simple: If the +errors+ method returns an empty collection, the object is valid and can be saved. Each time a validation fails, an error message is added to the +errors+ collection.
 
+h4. Object#invalid?
+
 h3. Declarative Validation Helpers
 
 Active Record offers many pre-defined validation helpers that you can use directly inside your class definitions. These helpers create validation rules that are commonly used. Every time a validation fails, an error message is added to the object's +errors+ collection, and this message is associated with the field being validated. 
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index 9dfcc3a3e7..bdd2a9d429 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -472,7 +472,7 @@ end
 
 This code sets the +@posts+ instance variable to an array of all posts in the database. +Post.find(:all)+ or +Post.all+ calls the +Post+ model to return all of the posts that are currently in the database, with no limiting conditions.
 
-TIP. For more information on finding records with Active Record, see "Active Record Finders":finders.html.
+TIP: For more information on finding records with Active Record, see "Active Record Finders":finders.html.
 
 The +respond_to+ block handles both HTML and XML calls to this action. If you browse to +http://localhost:3000/posts.xml+, you'll see all of the posts in XML format. The HTML format looks for a view in +app/views/posts/+ with a name that corresponds to the action name. Rails makes all of the instance variables from the action available to the view. Here's +app/view/posts/index.html.erb+:
 
@@ -493,7 +493,8 @@ The +respond_to+ block handles both HTML and XML calls to this action. If you br
     <td><%=h post.content %></td>
     <td><%= link_to 'Show', post %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
-    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
+    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', 
+            :method => :delete %></td>
   </tr>
 <% end %>
 </table>
@@ -521,7 +522,8 @@ The view is only part of the story of how HTML is displayed in your web browser.
 
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
-  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
+  <meta http-equiv="content-type" 
+        content="text/html;charset=UTF-8" />
   <title>Posts: <%= controller.action_name %></title>
   <%= stylesheet_link_tag 'scaffold' %>
 </head>
@@ -594,10 +596,12 @@ def create
     if @post.save
       flash[:notice] = 'Post was successfully created.'
       format.html { redirect_to(@post) }
-      format.xml  { render :xml => @post, :status => :created, :location => @post }
+      format.xml  { render :xml => @post, :status => :created, 
+	                :location => @post }
     else
       format.html { render :action => "new" }
-      format.xml  { render :xml => @post.errors, :status => :unprocessable_entity }
+      format.xml  { render :xml => @post.errors, 
+	                :status => :unprocessable_entity }
     end
   end
 end
@@ -697,7 +701,8 @@ def update
       format.xml  { head :ok }
     else
       format.html { render :action => "edit" }
-      format.xml  { render :xml => @post.errors, :status => :unprocessable_entity }
+      format.xml  { render :xml => @post.errors, 
+	                :status => :unprocessable_entity }
     end
   end
 end
@@ -733,7 +738,7 @@ h4. Using Partials to Eliminate View Duplication
 
 As you saw earlier, the scaffold-generated views for the +new+ and +edit+ actions are largely identical. You can pull the shared code out into a partial template. This requires editing the new and edit views, and adding a new template. The new +_form.html.erb+ template should be saved in the same +app/views/posts+ folder as the files from which it is being extracted. Note that the name of this file begins with an underscore; that's the Rails naming convention for partial templates.
 
-+new.html.erb+:
+<tt>new.html.erb</tt>:
 
 <html>
 <h1>New post</h1>
@@ -743,7 +748,7 @@ As you saw earlier, the scaffold-generated views for the +new+ and +edit+ action
 <%= link_to 'Back', posts_path %>
 </html>
 
-+edit.html.erb+:
+<tt>edit.html.erb</tt>:
 
 <erb>
 <h1>Editing post</h1>
@@ -754,7 +759,7 @@ As you saw earlier, the scaffold-generated views for the +new+ and +edit+ action
 <%= link_to 'Back', posts_path %>
 </erb>
 
-+_form.html.erb+:
+<tt>_form.html.erb</tt>:
 
 <erb>
 <% form_for(@post) do |f| %>
@@ -814,7 +819,8 @@ Four instances of the exact same line of code doesn’t seem very DRY. Rails pro
 
 <ruby>
 class PostsController < ApplicationController
-  before_filter :find_post, :only => [:show, :edit, :update, :destroy]
+  before_filter :find_post, 
+    :only => [:show, :edit, :update, :destroy]
   # ...
   def show
   # ... 
@@ -851,7 +857,8 @@ h4. Generating a Model
 Models in Rails use a singular name, and their corresponding database tables use a plural name. For the model to hold comments, the convention is to use the name Comment. Even if you don't want to use the entire apparatus set up by scaffolding, most Rails developers still use generators to make things like models and controllers. To create the new model, run this command in your terminal:
 
 <shell>
-$ script/generate model Comment commenter:string body:text post:references
+$ script/generate model Comment commenter:string body:text 
+    post:references
 </shell>
 
 This command will generate four files:
@@ -1064,8 +1071,13 @@ The +views/comments/index.html.erb+ view:
     <td><%=h comment.commenter %></td>
     <td><%=h comment.body %></td>
     <td><%= link_to 'Show', post_comment_path(@post, comment) %></td>
-    <td><%= link_to 'Edit', edit_post_comment_path(@post, comment) %></td>
-    <td><%= link_to 'Destroy', post_comment_path(@post, comment), :confirm => 'Are you sure?', :method => :delete %></td>
+    <td>
+        <%= link_to 'Edit', edit_post_comment_path(@post, comment) %>
+    </td>
+    <td>
+        <%= link_to 'Destroy', post_comment_path(@post, comment), 
+            :confirm => 'Are you sure?', :method => :delete %>
+    </td>
   </tr>
 <% end %>
 </table>
diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile
index ec02c5aeb6..53a0cc2834 100644
--- a/railties/guides/source/i18n.textile
+++ b/railties/guides/source/i18n.textile
@@ -91,7 +91,7 @@ This means, that in the +:en+ locale, the key _hello_ will map to _Hello world_
 
 The I18n library will use *English* as a *default locale*, ie. if you don't set a different locale, +:en+ will be used for looking up translations.
 
-NOTE: The i18n library takes *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". (For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have €. Also, insults would be different in American and British English :) Reason for this pragmatic approach is that most of the time, you usually care about making your application available in different "languages", and working with locales is much simpler this way. However, nothing stops you from separating regional and other settings in the traditional way. In this case, you could eg. inherit from the default +en+ locale and then provide UK specific settings in a +:en-UK+ dictionary.
+NOTE: The i18n library takes *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". (For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Also, insults would be different in American and British English :) Reason for this pragmatic approach is that most of the time, you usually care about making your application available in different "languages", and working with locales is much simpler this way. However, nothing stops you from separating regional and other settings in the traditional way. In this case, you could eg. inherit from the default +en+ locale and then provide UK specific settings in a +:en-UK+ dictionary.
 
 The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you. 
 
diff --git a/railties/guides/source/index.erb.textile b/railties/guides/source/index.erb.textile
index 599e55b660..fd38ae0d9c 100644
--- a/railties/guides/source/index.erb.textile
+++ b/railties/guides/source/index.erb.textile
@@ -11,7 +11,7 @@ These guides are designed to make you immediately productive with Rails, and to
 <% content_for :index_section do %>
 <div id="subCol">
   <dl>
-    <dd class="warning">This page is the result of ongoing Rails Guides hackfest and a work in progress.</dd>
+    <dd class="warning">Rails Guides are a result of the ongoing "Guides hackfest":http://hackfest.rubyonrails.org and a work in progress.</dd>
     <dd class="ticket">Guides marked with this icon are currently being worked on. While they might still be useful to you, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections at the respective Lighthouse ticket.</dd>
   </dl>
 </div>