Module: ActiveRecord::Scoping::Named::ClassMethods

Defined in:
lib/active_record/scoping/named.rb

Instance Method Summary collapse

Instance Method Details

#all ⇒ Object

Returns an ActiveRecord::Relation scope object.

posts = Post.all
posts.size # Fires "select count(*) from  posts" and returns the count
posts.each {|p| puts p.name } # Fires "select * from posts" and loads post objects

fruits = Fruit.all
fruits = fruits.where(color: 'red') if options[:red_only]
fruits = fruits.limit(10) if limited?

You can define a scope that applies to all finders using default_scope.



26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/active_record/scoping/named.rb', line 26

def all
  current_scope = self.current_scope

  if current_scope
    if self == current_scope.klass
      current_scope.clone
    else
      relation.merge!(current_scope)
    end
  else
    default_scoped
  end
end

#default_extensions ⇒ Object

:nodoc:



54
55
56
57
58
59
60
 
# File 'lib/active_record/scoping/named.rb', line 54

def default_extensions # :nodoc:
  if scope = current_scope || build_default_scope
    scope.extensions
  else
    []
  end
end

#default_scoped(scope = relation) ⇒ Object

:nodoc:



50
51
52
 
# File 'lib/active_record/scoping/named.rb', line 50

def default_scoped(scope = relation) # :nodoc:
  build_default_scope(scope) || scope
end

#scope(name, body, &block) ⇒ Object

Adds a class method for retrieving and querying objects. The method is intended to return an ActiveRecord::Relation object, which is composable with other scopes. If it returns nil or false, an all scope is returned instead.

A scope represents a narrowing of a database query, such as where(color: :red).select('shirts.*').includes(:washing_instructions).

class Shirt < ActiveRecord::Base
  scope :red, -> { where(color: 'red') }
  scope :dry_clean_only, -> { joins(:washing_instructions).where('washing_instructions.dry_clean_only = ?', true) }
end

The above calls to #scope define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red, in effect, represents the query Shirt.where(color: 'red').

You should always pass a callable object to the scopes defined with #scope. This ensures that the scope is re-evaluated each time it is called.

Note that this is simply 'syntactic sugar' for defining an actual class method:

class Shirt < ActiveRecord::Base
  def self.red
    where(color: 'red')
  end
end

Unlike Shirt.find(...), however, the object returned by Shirt.red is not an Array but an ActiveRecord::Relation, which is composable with other scopes; it resembles the association object constructed by a has_many declaration. For instance, you can invoke Shirt.red.first, Shirt.red.count, Shirt.red.where(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 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_only will return all of Elton's red, dry clean only shirts.

Named scopes can also have extensions, just as with has_many declarations:

class Shirt < ActiveRecord::Base
  scope :red, -> { where(color: 'red') } do
    def dom_id
      'red_shirts'
    end
  end
end

Scopes can also be used while creating/building a record.

class Article < ActiveRecord::Base
  scope :published, -> { where(published: true) }
end

Article.published.new.published    # => true
Article.published.create.published # => true

Class methods on your model are automatically available on scopes. Assuming the following setup:

class Article < ActiveRecord::Base
  scope :published, -> { where(published: true) }
  scope :featured, -> { where(featured: true) }

  def self.latest_article
    order('published_at desc').first
  end

  def self.titles
    pluck(:title)
  end
end

We are able to call the methods like this:

Article.published.featured.latest_article
Article.featured.titles



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/active_record/scoping/named.rb', line 163

def scope(name, body, &block)
  unless body.respond_to?(:call)
    raise ArgumentError, "The scope body needs to be callable."
  end

  if dangerous_class_method?(name)
    raise ArgumentError, "You tried to define a scope named \"#{name}\" " \
      "on the model \"#{self.name}\", but Active Record already defined " \
      "a class method with the same name."
  end

  if method_defined_within?(name, Relation)
    raise ArgumentError, "You tried to define a scope named \"#{name}\" " \
      "on the model \"#{self.name}\", but ActiveRecord::Relation already defined " \
      "an instance method with the same name."
  end

  valid_scope_name?(name)
  extension = Module.new(&block) if block

  if body.respond_to?(:to_proc)
    singleton_class.send(:define_method, name) do |*args|
      scope = all
      scope = scope._exec_scope(*args, &body)
      scope = scope.extending(extension) if extension
      scope
    end
  else
    singleton_class.send(:define_method, name) do |*args|
      scope = all
      scope = scope.scoping { body.call(*args) || scope }
      scope = scope.extending(extension) if extension
      scope
    end
  end

  generate_relation_method(name)
end

#scope_for_association(scope = relation) ⇒ Object

:nodoc:



40
41
42
43
44
45
46
47
48
 
# File 'lib/active_record/scoping/named.rb', line 40

def scope_for_association(scope = relation) # :nodoc:
  current_scope = self.current_scope

  if current_scope && current_scope.empty_scope?
    scope
  else
    default_scoped(scope)
  end
end