Methods
N
S
Instance Public methods
named_scope(name, options = {}, &block)

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_scopedefine 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_manydeclaration. 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_onlywill 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.countreturns 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 descendant 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_onlywill 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_optionsmethod 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
# File activerecord/lib/active_record/named_scope.rb, line 86
def named_scope(name, options = {}, &block)
  name = name.to_sym
  scopes[name] = lambda do |parent_scope, *args|
    Scope.new(parent_scope, case options
      when Hash
        options
      when Proc
        if self.model_name != parent_scope.model_name
          options.bind(parent_scope).call(*args)
        else
          options.call(*args)
        end
    end, &block)
  end
  singleton_class.send :define_method, name do |*args|
    scopes[name].call(self, *args)
  end
end
scoped(scope, &block)
# File activerecord/lib/active_record/named_scope.rb, line 19
def scoped(scope, &block)
  Scope.new(self, scope, &block)
end
scopes()
# File activerecord/lib/active_record/named_scope.rb, line 15
def scopes
  read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
end