document the reorder method(fb215110401c70cfc7013c6e2ad5753fa4e374e9)

1 files changed, 31 insertions, 4 deletions

diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 2f0a51e868..579a323d57 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -56,6 +56,7 @@ The methods are:
 * +select+
 * +group+
 * +order+
+* +reorder+
 * +limit+
 * +offset+
 * +joins+
@@ -495,9 +496,9 @@ This will return single order objects for each day, but only for the last month.
 
 h3. Overriding Conditions
 
-You can specify certain conditions to be excepted by using the +except+ method.
+h4. +except+
 
-For example:
+You can specify certain conditions to be excepted by using the +except+ method. For example:
 
 <ruby>
 Post.where('id > 10').limit(20).order('id asc').except(:order)
@@ -509,9 +510,9 @@ The SQL that would be executed:
 SELECT * FROM posts WHERE id > 10 LIMIT 20
 </sql>
 
-You can also override conditions using the +only+ method.
+h4. +only+
 
-For example:
+You can also override conditions using the +only+ method. For example:
 
 <ruby>
 Post.where('id > 10').limit(20).order('id desc').only(:order, :where)
@@ -523,6 +524,32 @@ The SQL that would be executed:
 SELECT * FROM posts WHERE id > 10 ORDER BY id DESC
 </sql>
 
+h4. +reorder+
+
+The +reorder+ method overrides the default scope order. For example:
+
+<ruby>
+class Post < ActiveRecord::Base
+  ..
+  ..
+  has_many :comments, :order => 'posted_at DESC'
+end
+
+Post.find(10).comments.reorder('name')
+</ruby>
+
+The SQL that would be executed:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY name
+</sql>
+
+In case the +reorder+ clause is not used, the SQL executed would be:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC
+</sql>
+
 h3. Readonly Objects
 
 Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.