Module: WillPaginate::Finder::ClassMethods

Defined in:
lib/will_mostly_paginate/finder.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#paginate(*args) ⇒ Object

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”)

  • :page_all – whether or not to count the total number of pages

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



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/will_mostly_paginate/finder.rb', line 65

def paginate(*args)
  options = args.pop
  page, per_page, total_entries, page_all = wp_parse_options(options)
  finder = (options[:finder] || 'find').to_s

  if finder == 'find'
    # an array of IDs may have been given:
    total_entries ||= (Array === args.first and args.first.size)
    # :all is implicit
    args.unshift(:all) if args.empty?
  end

  WillPaginate::Collection.create(page, per_page, total_entries, page_all) do |pager|
    count_options = options.except :page, :per_page, :total_entries, :page_all, :finder
    find_options = count_options.except(:count).update(:offset => pager.offset, :limit => pager.per_page + (page_all ? 0 : 1))

    args << find_options
    results = send(finder, *args) { |*a| yield(*a) if block_given? }

    if page_all
      pager.replace(results)
      # magic counting for user convenience:
      pager.total_entries = wp_count(count_options, args, finder) unless pager.total_entries
    else
      # If we're not paging all pages, then we only need to know if the next page exists
      if results.length > pager.per_page
        pager.next_exists = true
        pager.replace(results[0..-2])
      else
        pager.next_exists = false
        pager.replace(results)
      end
    end
  end
end

#paginate_by_sql(sql, options) ⇒ Object

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.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/will_mostly_paginate/finder.rb', line 143

def paginate_by_sql(sql, options)
  WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
    query = sanitize_sql(sql.dup)
    original_query = query.dup
    # add limit, offset
    add_limit! query, :offset => pager.offset, :limit => pager.per_page
    # perfom the find
    pager.replace find_by_sql(query)

    unless pager.total_entries
      count_query = original_query.sub /\bORDER\s+BY\s+[\w`,\s]+$/mi, ''
      count_query = "SELECT COUNT(*) FROM (#{count_query})"

      unless self.connection.adapter_name =~ /^(oracle|oci$)/i
        count_query << ' AS count_table'
      end
      # perform the count query
      pager.total_entries = count_by_sql(count_query)
    end
  end
end

#paginated_each(options = {}) ⇒ Object

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.



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/will_mostly_paginate/finder.rb', line 111

def paginated_each(options = {})
  options = { :order => 'id', :page => 1 }.merge options
  options[:page] = options[:page].to_i
  options[:total_entries] = 0 # skip the individual count queries
  total = 0

  begin
    collection = paginate(options)
    with_exclusive_scope(:find => {}) do
      # using exclusive scope so that the block is yielded in scope-free context
      total += collection.each { |item| yield item }.size
    end
    options[:page] += 1
  end until collection.size < collection.per_page

  total
end

#respond_to?(method, include_priv = false) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


165
166
167
168
169
170
171
172
 
# File 'lib/will_mostly_paginate/finder.rb', line 165

def respond_to?(method, include_priv = false) #:nodoc:
  case method.to_sym
  when :paginate, :paginate_by_sql
    true
  else
    super || super(method.to_s.sub(/^paginate/, 'find'), include_priv)
  end
end