Module WillPaginate::Finder::ClassMethods
In: lib/will_paginate/finder.rb
ArgumentError InvalidPage Array Collection LinkRenderer Scope ViewHelpers Finder Finder::ClassMethods lib/will_paginate/collection.rb lib/will_paginate/view_helpers.rb ViewHelpers ClassMethods Finder VERSION Deprecation lib/will_paginate/named_scope.rb ClassMethods NamedScope WillPaginate dot/m_8_0.png

Paginating finders for ActiveRecord models

WillPaginate adds paginate, per_page and other methods to ActiveRecord::Base class methods and associations. It also hooks into method_missing to intercept pagination calls to dynamic finders such as paginate_by_user_id and translate them to ordinary finders (find_all_by_user_id in this case).

In short, paginating finders are equivalent to ActiveRecord finders; the only difference is that we start with "paginate" instead of "find" and that :page is required parameter:

  @posts = Post.paginate :all, :page => params[:page], :order => 'created_at DESC'

In paginating finders, "all" is implicit. There is no sense in paginating a single record, right? So, you can drop the :all argument:

  Post.paginate(...)              =>  Post.find :all
  Post.paginate_all_by_something  =>  Post.find_all_by_something
  Post.paginate_by_something      =>  Post.find_all_by_something

The importance of the :order parameter

In ActiveRecord finders, :order parameter specifies columns for the ORDER BY clause in SQL. It is important to have it, since pagination only makes sense with ordered sets. Without the ORDER BY clause, databases aren‘t required to do consistent ordering when performing SELECT queries; this is especially true for PostgreSQL.

Therefore, make sure you are doing ordering on a column that makes the most sense in the current context. Make that obvious to the user, also. For perfomance reasons you will also want to add an index to that column.

Methods

Public Instance methods

This is the main paginating finder.

Special parameters for paginating finders

  • :page — REQUIRED, but defaults to 1 if false or nil
  • :per_page — defaults to CurrentModel.per_page (which is 30 if not overridden)
  • :total_entries — use only if you manually count total entries
  • :count — additional options that are passed on to count
  • :finder — name of the ActiveRecord finder used (default: "find")

All other options (conditions, order, …) are forwarded to find and count calls.

[Source]

    # File lib/will_paginate/finder.rb, line 64
64:       def paginate(*args, &block)
65:         options = args.pop
66:         page, per_page, total_entries = wp_parse_options(options)
67:         finder = (options[:finder] || 'find').to_s
68: 
69:         if finder == 'find'
70:           # an array of IDs may have been given:
71:           total_entries ||= (Array === args.first and args.first.size)
72:           # :all is implicit
73:           args.unshift(:all) if args.empty?
74:         end
75: 
76:         WillPaginate::Collection.create(page, per_page, total_entries) do |pager|
77:           count_options = options.except :page, :per_page, :total_entries, :finder
78:           find_options = count_options.except(:count).update(:offset => pager.offset, :limit => pager.per_page) 
79:           
80:           args << find_options
81:           # @options_from_last_find = nil
82:           pager.replace send(finder, *args, &block)
83:           
84:           # magic counting for user convenience:
85:           pager.total_entries = wp_count(count_options, args, finder) unless pager.total_entries
86:         end
87:       end

Wraps find_by_sql by simply adding LIMIT and OFFSET to your SQL string based on the params otherwise used by paginating finds: page and per_page.

Example:

  @developers = Developer.paginate_by_sql ['select * from developers where salary > ?', 80000],
                         :page => params[:page], :per_page => 3

A query for counting rows will automatically be generated if you don‘t supply :total_entries. If you experience problems with this generated SQL, you might want to perform the count manually in your application.

[Source]

     # File lib/will_paginate/finder.rb, line 128
128:       def paginate_by_sql(sql, options)
129:         WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
130:           query = sanitize_sql(sql)
131:           original_query = query.dup
132:           # add limit, offset
133:           add_limit! query, :offset => pager.offset, :limit => pager.per_page
134:           # perfom the find
135:           pager.replace find_by_sql(query)
136:           
137:           unless pager.total_entries
138:             count_query = original_query.sub /\bORDER\s+BY\s+[\w`,\s]+$/mi, ''
139:             count_query = "SELECT COUNT(*) FROM (#{count_query})"
140:             
141:             unless ['oracle', 'oci'].include?(self.connection.adapter_name.downcase)
142:               count_query << ' AS count_table'
143:             end
144:             # perform the count query
145:             pager.total_entries = count_by_sql(count_query)
146:           end
147:         end
148:       end

Iterates through all records by loading one page at a time. This is useful for migrations or any other use case where you don‘t want to load all the records in memory at once.

It uses paginate internally; therefore it accepts all of its options. You can specify a starting page with :page (default is 1). Default :order is "id", override if necessary.

See weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord where Jamis Buck describes this and also uses a more efficient way for MySQL.

[Source]

     # File lib/will_paginate/finder.rb, line 99
 99:       def paginated_each(options = {}, &block)
100:         options = { :order => 'id', :page => 1 }.merge options
101:         options[:page] = options[:page].to_i
102:         options[:total_entries] = 0 # skip the individual count queries
103:         total = 0
104:         
105:         begin 
106:           collection = paginate(options)
107:           total += collection.each(&block).size
108:           options[:page] += 1
109:         end until collection.size < collection.per_page
110:         
111:         total
112:       end

Protected Instance methods

Does the not-so-trivial job of finding out the total number of entries in the database. It relies on the ActiveRecord count method.

[Source]

     # File lib/will_paginate/finder.rb, line 182
182:       def wp_count(options, args, finder)
183:         excludees = [:count, :order, :limit, :offset, :readonly]
184:         unless options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
185:           excludees << :select # only exclude the select param if it doesn't begin with DISTINCT
186:         end
187:         # count expects (almost) the same options as find
188:         count_options = options.except *excludees
189: 
190:         # merge the hash found in :count
191:         # this allows you to specify :select, :order, or anything else just for the count query
192:         count_options.update options[:count] if options[:count]
193: 
194:         # we may have to scope ...
195:         counter = Proc.new { count(count_options) }
196: 
197:         # we may be in a model or an association proxy!
198:         klass = (@owner and @reflection) ? @reflection.klass : self
199: 
200:         count = if finder.index('find_') == 0 and klass.respond_to?(scoper = finder.sub('find', 'with'))
201:                   # scope_out adds a 'with_finder' method which acts like with_scope, if it's present
202:                   # then execute the count with the scoping provided by the with_finder
203:                   send(scoper, &counter)
204:                 elsif match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(finder)
205:                   # extract conditions from calls like "paginate_by_foo_and_bar"
206:                   attribute_names = extract_attribute_names_from_match(match)
207:                   conditions = construct_attributes_from_arguments(attribute_names, args)
208:                   with_scope(:find => { :conditions => conditions }, &counter)
209:                 else
210:                   counter.call
211:                 end
212: 
213:         count.respond_to?(:length) ? count.length : count
214:       end

[Validate]