Module | WillPaginate::Finder::ClassMethods |
In: |
lib/will_paginate/finder.rb
|
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
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.
This is the main paginating finder.
All other options (conditions, order, …) are forwarded to find and count calls.
# File lib/will_paginate/finder.rb, line 64 64: def paginate(*args) 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) { |*a| yield(*a) if block_given? }) 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.
# File lib/will_paginate/finder.rb, line 131 131: def paginate_by_sql(sql, options) 132: WillPaginate::Collection.create(*wp_parse_options(options)) do |pager| 133: query = sanitize_sql(sql.dup) 134: original_query = query.dup 135: # add limit, offset 136: add_limit! query, :offset => pager.offset, :limit => pager.per_page 137: # perfom the find 138: pager.replace find_by_sql(query) 139: 140: unless pager.total_entries 141: count_query = original_query.sub /\bORDER\s+BY\s+[\w`,\s]+$/mi, '' 142: count_query = "SELECT COUNT(*) FROM (#{count_query})" 143: 144: unless self.connection.adapter_name =~ /^(oracle|oci$)/i 145: count_query << ' AS count_table' 146: end 147: # perform the count query 148: pager.total_entries = count_by_sql(count_query) 149: end 150: end 151: 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 Faking Cursors in ActiveRecord where Jamis Buck describes this and a more efficient way for MySQL.
# File lib/will_paginate/finder.rb, line 99 99: def paginated_each(options = {}) 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: with_exclusive_scope(:find => {}) do 108: # using exclusive scope so that the block is yielded in scope-free context 109: total += collection.each { |item| yield item }.size 110: end 111: options[:page] += 1 112: end until collection.size < collection.per_page 113: 114: total 115: end
Does the not-so-trivial job of finding out the total number of entries in the database. It relies on the ActiveRecord count method.
# File lib/will_paginate/finder.rb, line 189 189: def wp_count(options, args, finder) 190: excludees = [:count, :order, :limit, :offset, :readonly] 191: excludees << :from unless ActiveRecord::Calculations::CALCULATIONS_OPTIONS.include?(:from) 192: 193: # we may be in a model or an association proxy 194: klass = (@owner and @reflection) ? @reflection.klass : self 195: 196: # Use :select from scope if it isn't already present. 197: options[:select] = scope(:find, :select) unless options[:select] 198: 199: if options[:select] and options[:select] =~ /^\s*DISTINCT\b/i 200: # Remove quoting and check for table_name.*-like statement. 201: if options[:select].gsub('`', '') =~ /\w+\.\*/ 202: options[:select] = "DISTINCT #{klass.table_name}.#{klass.primary_key}" 203: end 204: else 205: excludees << :select # only exclude the select param if it doesn't begin with DISTINCT 206: end 207: 208: # count expects (almost) the same options as find 209: count_options = options.except *excludees 210: 211: # merge the hash found in :count 212: # this allows you to specify :select, :order, or anything else just for the count query 213: count_options.update options[:count] if options[:count] 214: 215: # forget about includes if they are irrelevant (Rails 2.1) 216: if count_options[:include] and 217: klass.private_methods.include_method?(:references_eager_loaded_tables?) and 218: !klass.send(:references_eager_loaded_tables?, count_options) 219: count_options.delete :include 220: end 221: 222: # we may have to scope ... 223: counter = Proc.new { count(count_options) } 224: 225: count = if finder.index('find_') == 0 and klass.respond_to?(scoper = finder.sub('find', 'with')) 226: # scope_out adds a 'with_finder' method which acts like with_scope, if it's present 227: # then execute the count with the scoping provided by the with_finder 228: send(scoper, &counter) 229: elsif finder =~ /^find_(all_by|by)_([_a-zA-Z]\w*)$/ 230: # extract conditions from calls like "paginate_by_foo_and_bar" 231: attribute_names = $2.split('_and_') 232: conditions = construct_attributes_from_arguments(attribute_names, args) 233: with_scope(:find => { :conditions => conditions }, &counter) 234: else 235: counter.call 236: end 237: 238: count.respond_to?(:length) ? count.length : count 239: end