Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 146 lines (96 sloc) 5.516 kB
1d8029f @rwdaigle Pulling docs into README
rwdaigle authored
1 h1. Utility Scopes
2
3 h2. Summary
4
5 Utility scopes provides a collection of utilitarian "named scopes":http://api.rubyonrails.com/classes/ActiveRecord/NamedScope/ClassMethods.html#M001246 for use with your
6 ActiveRecord models.
7
8
9 Utility scopes was originally announced "here":http://ryandaigle.com/articles/2008/8/20/named-scope-it-s-not-just-for-conditions-ya-know and has expanded in scope and functionality since then thanks to user contributions. See the
10 "CHANGELOG":http://github.com/yfactorial/utility_scopes/tree/master/CHANGELOG for contribution details.
11
12 Utility scopes has the following dependencies:
13
14 * activerecord >= 2.1.0
15 * rspec >= 1.1.4 (for specs only, not runtime)
16
1bc47f4 @rwdaigle Updating README
rwdaigle authored
17 h2. Installation
1d8029f @rwdaigle Pulling docs into README
rwdaigle authored
18
19 To install the utility_scopes gem run the following:
20
7937aed @rwdaigle Update README to reflect new gemcutter hosting
rwdaigle authored
21 sudo gem install utility_scopes
1bc47f4 @rwdaigle Updating README
rwdaigle authored
22
23 And to enable the scopes in your project just require @utility_scopes@:
24
25 require 'utility_scopes'
26
27 h3. Rails
1d8029f @rwdaigle Pulling docs into README
rwdaigle authored
28
29 You can also specify the gem dependency if you're running Rails 2.1 in your @config/environment.rb@ file:
30
31 Rails::Initializer.run do |config|
32 # ...
7937aed @rwdaigle Update README to reflect new gemcutter hosting
rwdaigle authored
33 config.gem "utility_scopes"
1bc47f4 @rwdaigle Updating README
rwdaigle authored
34 end
35
36 You don't need to @require 'utility_scopes'@ in this case as Rails will automatically require it.
37
38 h2. Scopes
39
40 Most examples assume the following @Article@ class:
41
42 class Article < ActiveRecord::Base
43 has_many :comments # (assume each comment also has a :user)
44 has_many :contributors
45 belongs_to :author, :class_name => 'User'
46 end
47
48 Named scopes are chainable by nature, meaning that the following is possible:
49
50 Article.with(:comments).except(1, 2, 3).ordered.limited(5)
51
52 Any exceptions to chainable scopes will be specified in their section below.
53
54 h3. With (eager-loading)
55
56 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
57 the @with@ named scope:
58
e53cf1a @rwdaigle Fixing README formatting
rwdaigle authored
59 <pre><code>
1bc47f4 @rwdaigle Updating README
rwdaigle authored
60 # Get all articles and eager-load their comments, each comments' user, article contributors
61 # and the article author.
62 Article.with({ :comments => :user }, :contributors, :author)
63
64 # Get all articles and eager-load their comments
65 Article.with(:comments)
e53cf1a @rwdaigle Fixing README formatting
rwdaigle authored
66 </code></pre>
1bc47f4 @rwdaigle Updating README
rwdaigle authored
67
68 Again, just pass in the same arguments into @eager@ that you would pass in as the @:include@ value to "ActiveRecord::Base#find":http://api.rubyonrails.com/classes/ActiveRecord/Base.html#M001298
69
70 h3. Except
71
72 _contributed by danielmorrison_
73
74 @except@ excludes the given records from the result set:
75
76 Article.except(1, 2, 3) # Get all articles whose id is NOT 1, 2 or 3
77 Article.except(@article) # Get all articles except the given one
78 Article.except(@new_articles) # Get all non-new articles
79
80 h3. Limited
81
82 @limited@ lets you place a limit on the number of results returned. By default
83 the scope will limit the result set to 10 results if no argument is passed in:
84
85 Article.limited # Get the first 10 articles
86 Article.except(1).limited(5) # Get the first 5 articles where id != 1
87
88 If you're using "will_paginate":http://github.com/mislav/will_paginate/tree/master and don't
89 pass an argument to the scope then the @per_page@ value that is used by will_paginate
90 will be used:
91
92 Article.per_page #=> 20
93 Article.limited # Get the first 20 articles
94
95 If you would like to specify a different default value you can do so on a per class basis
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
96 using @default_limit@:
1bc47f4 @rwdaigle Updating README
rwdaigle authored
97
0274758 @rwdaigle Fixing README formatting
rwdaigle authored
98 <pre><code>
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
99 # Set the default limit to be 15
100 class Article < ActiveRecord::Base
101 default_limit 15
102 end
103
104 Article.limited # Get the first 15 articles
0274758 @rwdaigle Fixing README formatting
rwdaigle authored
105 </code></pre>
1bc47f4 @rwdaigle Updating README
rwdaigle authored
106
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
107 h3. Ordered
108
0274758 @rwdaigle Fixing README formatting
rwdaigle authored
109 _Note: the @ordered@ scope cannot be chained with any other @order@ clauses_
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
110
111 @ordered@ lets you dynamically specify the ordering of your result set. If no
849ae98 @rwdaigle Updated docs for new release with jney's ordered updates
rwdaigle authored
112 arguments are given it will default to @created_at DESC@. (@ordered@ is also
113 available as @order_by@ and @sort_by@)
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
114
7e7e935 @jney added alias "sort_by", "order_by" to named_scope "ordered"
jney authored
115 Article.ordered # Get all articles ordered by "created_at DESC"
116 Article.ordered(:id) # Get all articles ordered by "id"
117 Article.ordered("rank ASC") # Get all articles ordered by "rank ASC"
118 Article.order_by(:id) # order_by and sort_by are alias to ordered
849ae98 @rwdaigle Updated docs for new release with jney's ordered updates
rwdaigle authored
119 Article.order_by([:id, :desc], :popularity) # can take a two-element array as parameter
120 Article.sort_by(:id => :desc, :popularity => :asc) # can take a hash as parameter
8d51af9 @jney added ordered hash support for jruby and ruby 1.9
jney authored
121 # only available for jruby/ruby 1.9
7e7e935 @jney added alias "sort_by", "order_by" to named_scope "ordered"
jney authored
122 Article.order_by_id # can be set as a sentence
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
123
124 If you would like to specify a different default sort order you can do so on a per class basis
125 using @ordered_by@:
126
e53cf1a @rwdaigle Fixing README formatting
rwdaigle authored
127 <pre><code>
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
128 # Set the default order to be "published_at DESC"
129 class Article < ActiveRecord::Base
130 ordered_by 'published_at DESC'
131 end
132
133 Article.ordered # Get all articles ordered by "published_at DESC"
134 Article.ordered("rank ASC") # Get all articles ordered by "rank ASC"
e53cf1a @rwdaigle Fixing README formatting
rwdaigle authored
135 </code></pre>
35997ff @rwdaigle Filled out README with docs for all scopes
rwdaigle authored
136
137 The current default ordering for a class can always be accessed via @default_ordering@:
138
64b3b97 @rwdaigle Add pks utility scope
rwdaigle authored
139 Article.default_ordering #=> "published_at DESC"
140
141 h3. PKs
142
82411f2 @rwdaigle Added pks named scope and updated for release to gemcutter
rwdaigle authored
143 @only_pks@ selects only the primary key column. This is useful when combined with the @pks@ class method to get the primary key values as an array:
64b3b97 @rwdaigle Add pks utility scope
rwdaigle authored
144
145 Article.published.limited(10).only_pks # Get the first 10 published articles with only the 'id' value populated [<Article:XX>, <Article:XX>, ...]
146 Article.published.limited(10).pks # Get the first 10 published article ids: [1, 2, 3 ...]
Something went wrong with that request. Please try again.