Utility scopes provides a collection of utilitarian named scopes for use with your
ActiveRecord models.

Utility scopes was originally announced here and has expanded in scope and functionality since then thanks to user contributions. See the
CHANGELOG for contribution details.

Utility scopes has the following dependencies:

• activerecord >= 2.1.0
• rspec >= 1.1.4 (for specs only, not runtime)

To install the utility_scopes gem run the following:

And to enable the scopes in your project just require utility_scopes:

You can also specify the gem dependency if you’re running Rails 2.1 in your config/environment.rb file:

1. …
   config.gem “yfactorial-utility_scopes”, :lib => ‘utility_scopes’,
   :source => ‘https://gems.github.com/’
   end

You don’t need to require 'utility_scopes' in this case as Rails will automatically require it.

Most examples assume the following Article class:

Named scopes are chainable by nature, meaning that the following is possible:

Any exceptions to chainable scopes will be specified in their section below.

The with scope let’s you eager load your model associations. So instead of having to invoke find(:all, :include => [:association1, :association2]) just pass these association names into
the with named scope:

	
Get all articles and eager-load their comments, each comments’ user, article contributors
	
and the article author.

  Article.with({ :comments => :user }, :contributors, :author)


	
Get all articles and eager-load their comments

  Article.with(:comments)

  

Again, just pass in the same arguments into eager that you would pass in as the :include value to ActiveRecord::Base#find

contributed by danielmorrison

except excludes the given records from the result set:

limited lets you place a limit on the number of results returned. By default
the scope will limit the result set to 10 results if no argument is passed in:

If you’re using will_paginate and don’t
pass an argument to the scope then the per_page value that is used by will_paginate
will be used:

If you would like to specify a different default value you can do so on a per class basis
using default_limit:

	
Set the default limit to be 15  

  class Article < ActiveRecord::Base

    default_limit 15

  end

Article.limited  # Get the first 15 articles

Note: the ordered scope cannot be chained with any other order clauses

ordered lets you dynamically specify the ordering of your result set. If no
arguments are given it will default to created_at DESC:

If you would like to specify a different default sort order you can do so on a per class basis
using ordered_by:

	
Set the default order to be “published_at DESC”

  class Article < ActiveRecord::Base

    ordered_by ‘published_at DESC’

  end

Article.ordered              # Get all articles ordered by “published_at DESC”
Article.ordered(“rank ASC”)  # Get all articles ordered by “rank ASC”

The current default ordering for a class can always be accessed via default_ordering: