Adds a class method for retrieving and querying objects. A scope represents
a narrowing of a database query, such as :conditions => {:color
=> :red}, :select => ‘shirts.*’, :include =>
:washing_instructions.
class Shirt < ActiveRecord::Base
named_scope :red, :conditions => {:color => 'red'}
named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true]
end
The above calls to named_scope define class methods
Shirt.red and Shirt.dry_clean_only. Shirt.red, in effect, represents the
query Shirt.find(:all, :conditions => {:color =>
‘red’}).
Unlike Shirt.find(...), however, the object returned by Shirt.red
is not an Array; it resembles the association object constructed by a
has_many declaration. For instance, you can invoke
Shirt.red.find(:first), Shirt.red.count,
Shirt.red.find(:all, :conditions => {:size =>
‘small’}). Also, just as with the association objects,
named \scopes act like an Array,
implementing Enumerable;
Shirt.red.each(&block), Shirt.red.first, and
Shirt.red.inject(memo, &block) all behave as if Shirt.red
really was an Array.
These named \scopes are composable.
For instance, Shirt.red.dry_clean_only will produce all shirts
that are both red and dry clean only. Nested finds and calculations also
work with these compositions: Shirt.red.dry_clean_only.count
returns the number of garments for which these criteria obtain. Similarly
with Shirt.red.dry_clean_only.average(:thread_count).
All \scopes are available as class
methods on the ActiveRecord::Base descendent
upon which the \scopes were
defined. But they are also available to has_many associations. If,
class Person < ActiveRecord::Base
has_many :shirts
end
then elton.shirts.red.dry_clean_only will return all of
Elton‘s red, dry clean only shirts.
Named \scopes can also be
procedural:
class Shirt < ActiveRecord::Base
named_scope :colored, lambda { |color|
{ :conditions => { :color => color } }
}
end
In this example, Shirt.colored(‘puce’) finds all puce
shirts.
Named \scopes can also have
extensions, just as with has_many declarations:
class Shirt < ActiveRecord::Base
named_scope :red, :conditions => {:color => 'red'} do
def dom_id
'red_shirts'
end
end
end
For testing complex named \scopes,
you can examine the scoping options using the proxy_options method
on the proxy itself.
class Shirt < ActiveRecord::Base
named_scope :colored, lambda { |color|
{ :conditions => { :color => color } }
}
end
expected_options = { :conditions => { :colored => 'red' } }
assert_equal expected_options, Shirt.colored('red').proxy_options