247 lines
10 KiB
Ruby
247 lines
10 KiB
Ruby
require 'will_paginate/core_ext'
|
|
|
|
module WillPaginate
|
|
# A mixin for ActiveRecord::Base. Provides +per_page+ class method
|
|
# and hooks things up to provide paginating finders.
|
|
#
|
|
# Find out more in WillPaginate::Finder::ClassMethods
|
|
#
|
|
module Finder
|
|
def self.included(base)
|
|
base.extend ClassMethods
|
|
class << base
|
|
alias_method_chain :method_missing, :paginate
|
|
# alias_method_chain :find_every, :paginate
|
|
define_method(:per_page) { 30 } unless respond_to?(:per_page)
|
|
end
|
|
end
|
|
|
|
# = 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 <tt>:page</tt> 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 <tt>:all</tt> 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 <tt>:order</tt> parameter
|
|
#
|
|
# In ActiveRecord finders, <tt>:order</tt> parameter specifies columns for
|
|
# the <tt>ORDER BY</tt> clause in SQL. It is important to have it, since
|
|
# pagination only makes sense with ordered sets. Without the <tt>ORDER
|
|
# BY</tt> clause, databases aren't required to do consistent ordering when
|
|
# performing <tt>SELECT</tt> 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.
|
|
module ClassMethods
|
|
# This is the main paginating finder.
|
|
#
|
|
# == Special parameters for paginating finders
|
|
# * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
|
|
# * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 30 if not overridden)
|
|
# * <tt>:total_entries</tt> -- use only if you manually count total entries
|
|
# * <tt>:count</tt> -- additional options that are passed on to +count+
|
|
# * <tt>:finder</tt> -- name of the ActiveRecord finder used (default: "find")
|
|
#
|
|
# All other options (+conditions+, +order+, ...) are forwarded to +find+
|
|
# and +count+ calls.
|
|
def paginate(*args, &block)
|
|
options = args.pop
|
|
page, per_page, total_entries = 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) do |pager|
|
|
count_options = options.except :page, :per_page, :total_entries, :finder
|
|
find_options = count_options.except(:count).update(:offset => pager.offset, :limit => pager.per_page)
|
|
|
|
args << find_options
|
|
# @options_from_last_find = nil
|
|
pager.replace send(finder, *args, &block)
|
|
|
|
# magic counting for user convenience:
|
|
pager.total_entries = wp_count(count_options, args, finder) unless pager.total_entries
|
|
end
|
|
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 <tt>:page</tt> (default is 1). Default
|
|
# <tt>:order</tt> is <tt>"id"</tt>, override if necessary.
|
|
#
|
|
# See {Faking Cursors in ActiveRecord}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
|
|
# where Jamis Buck describes this and a more efficient way for MySQL.
|
|
def paginated_each(options = {}, &block)
|
|
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)
|
|
total += collection.each(&block).size
|
|
options[:page] += 1
|
|
end until collection.size < collection.per_page
|
|
|
|
total
|
|
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 <tt>:total_entries</tt>. If you experience problems with this
|
|
# generated SQL, you might want to perform the count manually in your
|
|
# application.
|
|
#
|
|
def paginate_by_sql(sql, options)
|
|
WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
|
|
query = sanitize_sql(sql)
|
|
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 ['oracle', 'oci'].include?(self.connection.adapter_name.downcase)
|
|
count_query << ' AS count_table'
|
|
end
|
|
# perform the count query
|
|
pager.total_entries = count_by_sql(count_query)
|
|
end
|
|
end
|
|
end
|
|
|
|
def respond_to?(method, include_priv = false) #:nodoc:
|
|
case method.to_sym
|
|
when :paginate, :paginate_by_sql
|
|
true
|
|
else
|
|
super(method.to_s.sub(/^paginate/, 'find'), include_priv)
|
|
end
|
|
end
|
|
|
|
protected
|
|
|
|
def method_missing_with_paginate(method, *args, &block) #:nodoc:
|
|
# did somebody tried to paginate? if not, let them be
|
|
unless method.to_s.index('paginate') == 0
|
|
return method_missing_without_paginate(method, *args, &block)
|
|
end
|
|
|
|
# paginate finders are really just find_* with limit and offset
|
|
finder = method.to_s.sub('paginate', 'find')
|
|
finder.sub!('find', 'find_all') if finder.index('find_by_') == 0
|
|
|
|
options = args.pop
|
|
raise ArgumentError, 'parameter hash expected' unless options.respond_to? :symbolize_keys
|
|
options = options.dup
|
|
options[:finder] = finder
|
|
args << options
|
|
|
|
paginate(*args, &block)
|
|
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.
|
|
def wp_count(options, args, finder)
|
|
excludees = [:count, :order, :limit, :offset, :readonly]
|
|
unless options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
|
|
excludees << :select # only exclude the select param if it doesn't begin with DISTINCT
|
|
end
|
|
|
|
# count expects (almost) the same options as find
|
|
count_options = options.except *excludees
|
|
|
|
# merge the hash found in :count
|
|
# this allows you to specify :select, :order, or anything else just for the count query
|
|
count_options.update options[:count] if options[:count]
|
|
|
|
# we may be in a model or an association proxy
|
|
klass = (@owner and @reflection) ? @reflection.klass : self
|
|
|
|
# forget about includes if they are irrelevant (Rails 2.1)
|
|
if count_options[:include] and
|
|
klass.private_methods.include?('references_eager_loaded_tables?') and
|
|
!klass.send(:references_eager_loaded_tables?, count_options)
|
|
count_options.delete :include
|
|
end
|
|
|
|
# we may have to scope ...
|
|
counter = Proc.new { count(count_options) }
|
|
|
|
count = if finder.index('find_') == 0 and klass.respond_to?(scoper = finder.sub('find', 'with'))
|
|
# scope_out adds a 'with_finder' method which acts like with_scope, if it's present
|
|
# then execute the count with the scoping provided by the with_finder
|
|
send(scoper, &counter)
|
|
elsif match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(finder)
|
|
# extract conditions from calls like "paginate_by_foo_and_bar"
|
|
attribute_names = extract_attribute_names_from_match(match)
|
|
conditions = construct_attributes_from_arguments(attribute_names, args)
|
|
with_scope(:find => { :conditions => conditions }, &counter)
|
|
else
|
|
counter.call
|
|
end
|
|
|
|
count.respond_to?(:length) ? count.length : count
|
|
end
|
|
|
|
def wp_parse_options(options) #:nodoc:
|
|
raise ArgumentError, 'parameter hash expected' unless options.respond_to? :symbolize_keys
|
|
options = options.symbolize_keys
|
|
raise ArgumentError, ':page parameter required' unless options.key? :page
|
|
|
|
if options[:count] and options[:total_entries]
|
|
raise ArgumentError, ':count and :total_entries are mutually exclusive'
|
|
end
|
|
|
|
page = options[:page] || 1
|
|
per_page = options[:per_page] || self.per_page
|
|
total = options[:total_entries]
|
|
[page, per_page, total]
|
|
end
|
|
|
|
private
|
|
|
|
# def find_every_with_paginate(options)
|
|
# @options_from_last_find = options
|
|
# find_every_without_paginate(options)
|
|
# end
|
|
end
|
|
end
|
|
end
|