aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorVijay Dev <vijaydev.cse@gmail.com>2012-02-01 23:19:38 +0530
committerVijay Dev <vijaydev.cse@gmail.com>2012-02-01 23:31:43 +0530
commit479f3b4054b7db8c0f9bd325c0e27c918223e02b (patch)
treed9d3e599a8ad48fe16ec7303744f6642bce64727
parent5850ea056054c0610ddc1461dcf71d26ff60fa70 (diff)
downloadrails-479f3b4054b7db8c0f9bd325c0e27c918223e02b.tar.gz
rails-479f3b4054b7db8c0f9bd325c0e27c918223e02b.tar.bz2
rails-479f3b4054b7db8c0f9bd325c0e27c918223e02b.zip
document the AR none method [ci skip]
-rw-r--r--activerecord/lib/active_record/relation/query_methods.rb14
-rw-r--r--railties/guides/source/active_record_querying.textile24
2 files changed, 31 insertions, 7 deletions
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 6a28d7b155..b6d762c2e2 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -201,26 +201,26 @@ module ActiveRecord
#
# The returned NullRelation inherits from Relation and implements the
# Null Object pattern so it is an object with defined null behavior:
- # it always returns an empty array of records and avoids any database query.
+ # it always returns an empty array of records and does not query the database.
#
# Any subsequent condition chained to the returned relation will continue
# generating an empty relation and will not fire any query to the database.
#
- # Used in cases where is needed a method or a scope that could return zero
- # results but the response has to be chainable.
+ # This is useful in scenarios where you need a chainable response to a method
+ # or a scope that could return zero results.
#
# For example:
#
# @posts = current_user.visible_posts.where(:name => params[:name])
- # # => the visible_post method response has to be a chainable Relation
+ # # => the visible_posts method is expected to return a chainable Relation
#
# def visible_posts
# case role
- # if 'Country Manager'
+ # when 'Country Manager'
# Post.where(:country => country)
- # if 'Reviewer'
+ # when 'Reviewer'
# Post.published
- # if 'Bad User'
+ # when 'Bad User'
# Post.none # => returning [] instead breaks the previous code
# end
# end
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 3b4f2befda..21bbc64255 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -608,6 +608,30 @@ SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
This method accepts *no* arguments.
+h3. Null Relation
+
+The +none+ method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results.
+
+<ruby>
+Post.none # returns an empty Relation and fires no queries.
+</ruby>
+
+<ruby>
+# The visible_posts method below is expected to return a Relation.
+@posts = current_user.visible_posts.where(:name => params[:name])
+
+def visible_posts
+ case role
+ when 'Country Manager'
+ Post.where(:country => country)
+ when 'Reviewer'
+ Post.published
+ when 'Bad User'
+ Post.none # => returning [] or nil breaks the caller code in this case
+ end
+end
+</ruby>
+
h3. Readonly Objects
Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.