will_paginate 2.3.16 → 3.0.pre

data/lib/will_paginate/finders/active_record.rb

@@ -0,0 +1,158 @@
+require 'will_paginate/finders/base'
+require 'active_record'
+
+module WillPaginate::Finders
+  # = 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
+  #
+  module ActiveRecord
+    include WillPaginate::Finders::Base
+    
+    # In Rails, this is automatically called to mix-in pagination functionality to ActiveRecord.
+    def self.enable!
+      ::ActiveRecord::Base.class_eval do
+        extend ActiveRecord
+      end
+
+      # support pagination on associations and scopes
+      [::ActiveRecord::Relation, ::ActiveRecord::Associations::AssociationCollection].each do |klass|
+        klass.send(:include, ActiveRecord)
+      end
+    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.dup)
+        original_query = query.dup
+        # add limit, offset
+        query << " LIMIT #{pager.per_page} OFFSET #{pager.offset}"
+        # 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
+
+  protected
+
+    def wp_query(options, pager, args, &block) #:nodoc:
+      finder = (options.delete(:finder) || 'find').to_s
+      find_options = options.except(:count).update(:offset => pager.offset, :limit => pager.per_page) 
+
+      if finder == 'find'
+        if Array === args.first and !pager.total_entries
+          pager.total_entries = args.first.size
+        end
+        args << :all if args.empty?
+      end
+      
+      args << find_options
+      pager.replace send(finder, *args, &block)
+      
+      unless pager.total_entries
+        # magic counting
+        pager.total_entries = wp_count(options, args, finder) 
+      end
+    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) #:nodoc:
+      # find out if we are in a model or an association proxy
+      klass = (@owner and @reflection) ? @reflection.klass : self
+      count_options = wp_parse_count_options(options, klass)
+
+      # 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 finder =~ /^find_(all_by|by)_([_a-zA-Z]\w*)$/
+                # extract conditions from calls like "paginate_by_foo_and_bar"
+                attribute_names = $2.split('_and_')
+                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_count_options(options, klass) #:nodoc:
+      excludees = [:count, :order, :limit, :offset, :readonly]
+      
+      # Use :select from scope if it isn't already present.
+      # FIXME: this triggers extra queries when going through associations
+      # if options[:select].blank? && current_scoped_methods && current_scoped_methods.select_values.present?
+      #   options[:select] = current_scoped_methods.select_values.join(", ")
+      # end
+      
+      if options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
+        # Remove quoting and check for table_name.*-like statement.
+        if options[:select].gsub('`', '') =~ /\w+\.\*/
+          options[:select] = "DISTINCT #{klass.table_name}.#{klass.primary_key}"
+        end
+      else
+        excludees << :select
+      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]
+      
+      # forget about includes if they are irrelevant when counting
+      if count_options[:include] and count_options[:conditions].blank? and count_options[:group].blank?
+        count_options.delete :include
+      end
+      
+      count_options
+    end
+  end
+end

data/lib/will_paginate/finders/active_resource.rb

@@ -0,0 +1,51 @@
+require 'will_paginate/finders/base'
+require 'active_resource'
+
+module WillPaginate::Finders
+  # Paginate your ActiveResource models.
+  # 
+  #   @posts = Post.paginate :all, :params => {
+  #              :page => params[:page], :order => 'created_at DESC'
+  #            }
+  # 
+  module ActiveResource
+    include WillPaginate::Finders::Base
+    
+  protected
+  
+    def wp_query(options, pager, args, &block) #:nodoc:
+      unless args.empty? or args.first == :all
+        raise ArgumentError, "finder arguments other than :all are not supported for pagination (#{args.inspect} given)"
+      end
+      params = (options[:params] ||= {})
+      params[:page] = pager.current_page
+      params[:per_page] = pager.per_page
+      
+      pager.replace find_every(options, &block)
+    end
+    
+    # Takes the format that Hash.from_xml produces out of an unknown type
+    # (produced by WillPaginate::Collection#to_xml_with_collection_type), 
+    # parses it into a WillPaginate::Collection,
+    # and forwards the result to the former +instantiate_collection+ method.
+    # It only does this for hashes that have a :type => "collection".
+    def instantiate_collection_with_collection(collection, prefix_options = {}) #:nodoc:
+      if collection.is_a?(Hash) && collection["type"] == "collection"
+        collectables = collection.values.find{ |c| c.is_a?(Hash) || c.is_a?(Array) }
+        collectables = [collectables].compact unless collectables.kind_of?(Array)
+        instantiated_collection = WillPaginate::Collection.create(collection["current_page"], collection["per_page"], collection["total_entries"]) do |pager|
+          pager.replace instantiate_collection_without_collection(collectables, prefix_options)
+        end
+      else
+        instantiate_collection_without_collection(collection, prefix_options)
+      end
+    end
+  end
+end
+
+ActiveResource::Base.class_eval do
+  extend WillPaginate::Finders::ActiveResource
+  class << self
+    # alias_method_chain :instantiate_collection, :collection
+  end
+end

data/lib/will_paginate/finders/base.rb

@@ -0,0 +1,112 @@
+require 'will_paginate/core_ext'
+
+module WillPaginate
+  module Finders
+    # = Database-agnostic finder module
+    # 
+    # Out of the box, will_paginate supports hooking in several ORMs to
+    # provide paginating finders based on their API. As of this writing, the
+    # supported libraries are:
+    #
+    # * ActiveRecord
+    # * DataMapper
+    # * Sequel
+    #
+    # It's easy to write your own adapter for anything that can load data with
+    # explicit limit and offset settings. DataMapper adapter is a nice and
+    # compact example of writing an adapter to bring the +paginate+ method to
+    # DataMapper models.
+    #
+    # == The importance of SQL's <tt>ORDER BY</tt>
+    #
+    # In most ORMs, <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 order clause,
+    # databases aren't required to do consistent ordering when performing
+    # <tt>SELECT</tt> queries.
+    # 
+    # Ordering by a field for which many records share the same value (e.g.
+    # "status") can still result in incorrect ordering with some databases (MS
+    # SQL and Postgres for instance). With these databases it's recommend that
+    # you order by primary key as well. That is, instead of ordering by
+    # "status DESC", use the alternative "status DESC, id DESC" and this will
+    # yield consistent results.
+    #
+    # 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 Base
+      def per_page
+        @per_page ||= 30
+      end
+      
+      def per_page=(limit)
+        @per_page = limit.to_i
+      end
+      
+      # 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 finder method to use (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)
+
+        WillPaginate::Collection.create(page, per_page, total_entries) do |pager|
+          query_options = options.except :page, :per_page, :total_entries
+          wp_query(query_options, pager, args, &block)
+        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.
+      #
+      # {Jamis Buck describes this}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
+      # and also uses 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
+      
+      protected
+        
+        def wp_parse_options(options) #:nodoc:
+          raise ArgumentError, 'parameter hash expected' unless Hash === options
+          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]
+          
+          return [page, per_page, total]
+        end
+        
+    end
+  end
+end

data/lib/will_paginate/finders/data_mapper.rb

@@ -0,0 +1,30 @@
+require 'will_paginate/finders/base'
+require 'dm-core'
+
+module WillPaginate::Finders
+  module DataMapper
+    include WillPaginate::Finders::Base
+
+  protected
+    
+    def wp_query(options, pager, args, &block) #:nodoc
+      find_options = options.except(:count).update(:offset => pager.offset, :limit => pager.per_page) 
+
+      pager.replace all(find_options, &block)
+      
+      unless pager.total_entries
+        pager.total_entries = wp_count(options)
+      end
+    end
+
+    def wp_count(options) #:nodoc
+      count_options = options.except(:count, :order)
+      # merge the hash found in :count
+      count_options.update options[:count] if options[:count]
+
+      count_options.empty?? count() : count(count_options)
+    end
+  end
+end
+
+DataMapper::Model.send(:include, WillPaginate::Finders::DataMapper)

data/lib/will_paginate/finders/sequel.rb

@@ -0,0 +1,23 @@
+require 'will_paginate/core_ext'
+require 'sequel'
+require 'sequel/extensions/pagination'
+
+existing_methods = Sequel::Dataset::Pagination.instance_methods
+
+Sequel::Dataset::Pagination.module_eval do
+  # it should quack like a WillPaginate::Collection
+  
+  alias :total_pages   :page_count  unless existing_methods.include_method? :total_pages
+  alias :per_page      :page_size   unless existing_methods.include_method? :per_page
+  alias :previous_page :prev_page   unless existing_methods.include_method? :previous_page
+  alias :total_entries :pagination_record_count unless existing_methods.include_method? :total_entries
+  
+  def out_of_bounds?
+    current_page > total_pages
+  end
+
+  # Current offset of the paginated collection
+  def offset
+    (current_page - 1) * per_page
+  end
+end

data/lib/will_paginate/finders.rb

@@ -0,0 +1,9 @@
+require 'will_paginate/core_ext'
+
+module WillPaginate
+  # Database logic for different ORMs
+  #
+  # See WillPaginate::Finders::Base
+  module Finders
+  end
+end

data/lib/will_paginate/railtie.rb

@@ -0,0 +1,26 @@
+require 'will_paginate'
+require 'will_paginate/collection'
+
+module WillPaginate
+  class Railtie < Rails::Railtie
+    railtie_name :will_paginate
+    
+    initializer "will_paginate.active_record" do |app|
+      if defined? ::ActiveRecord
+        require 'will_paginate/finders/active_record'
+        WillPaginate::Finders::ActiveRecord.enable!
+      end
+    end
+    
+    initializer "will_paginate.action_dispatch" do |app|
+      if defined? ::ActionDispatch::ShowExceptions
+        ActionDispatch::ShowExceptions.rescue_responses['WillPaginate::InvalidPage'] = :not_found
+      end
+    end
+    
+    initializer "will_paginate.action_view" do |app|
+      require 'will_paginate/view_helpers/action_view'
+      ActionView::Base.send(:include, WillPaginate::ViewHelpers::ActionView)
+    end
+  end
+end

data/lib/will_paginate/version.rb

@@ -1,8 +1,8 @@
-module WillPaginate
-  module VERSION
-    MAJOR = 2
-    MINOR = 3
-    TINY  = 16
+module WillPaginate #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 3
+    MINOR = 0
+    TINY  = 'pre'
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/will_paginate/view_helpers/action_view.rb

@@ -0,0 +1,142 @@
+require 'will_paginate/view_helpers/base'
+require 'action_view'
+require 'action_pack/version'
+require 'will_paginate/view_helpers/link_renderer'
+
+module WillPaginate
+  module ViewHelpers
+    # = ActionView helpers
+    # 
+    # This module serves for availability in ActionView templates. It also adds a new
+    # view helper: +paginated_section+.
+    # 
+    # == Using the helper without arguments
+    # If the helper is called without passing in the collection object, it will
+    # try to read from the instance variable inferred by the controller name.
+    # For example, calling +will_paginate+ while the current controller is
+    # PostsController will result in trying to read from the <tt>@posts</tt>
+    # variable. Example:
+    #
+    #   <%= will_paginate :id => true %>
+    #
+    # ... will result in <tt>@post</tt> collection getting paginated:
+    #
+    #   <div class="pagination" id="posts_pagination"> ... </div>
+    #
+    module ActionView
+      include WillPaginate::ViewHelpers::Base
+      
+      def will_paginate(collection = nil, options = {}) #:nodoc:
+        options, collection = collection, nil if collection.is_a? Hash
+        collection ||= infer_collection_from_controller
+
+        super(collection, options.symbolize_keys).try(:html_safe)
+      end
+      
+      def page_entries_info(collection = nil, options = {}) #:nodoc:
+        options, collection = collection, nil if collection.is_a? Hash
+        collection ||= infer_collection_from_controller
+        
+        super(collection, options.symbolize_keys).try(:html_safe)
+      end
+      
+      # Wrapper for rendering pagination links at both top and bottom of a block
+      # of content.
+      # 
+      #   <% paginated_section @posts do %>
+      #     <ol id="posts">
+      #       <% for post in @posts %>
+      #         <li> ... </li>
+      #       <% end %>
+      #     </ol>
+      #   <% end %>
+      #
+      # will result in:
+      #
+      #   <div class="pagination"> ... </div>
+      #   <ol id="posts">
+      #     ...
+      #   </ol>
+      #   <div class="pagination"> ... </div>
+      #
+      # Arguments are passed to a <tt>will_paginate</tt> call, so the same options
+      # apply. Don't use the <tt>:id</tt> option; otherwise you'll finish with two
+      # blocks of pagination links sharing the same ID (which is invalid HTML).
+      def paginated_section(*args, &block)
+        pagination = will_paginate(*args).to_s
+        
+        unless ::ActionView::Base.respond_to? :erb_variable
+          concat pagination
+          yield
+          concat pagination
+        else
+          content = pagination + capture(&block) + pagination
+          concat(content, block.binding)
+        end
+      end
+      
+    protected
+
+      def infer_collection_from_controller
+        collection_name = "@#{controller.controller_name}"
+        collection = instance_variable_get(collection_name)
+        raise ArgumentError, "The #{collection_name} variable appears to be empty. Did you " +
+          "forget to pass the collection object for will_paginate?" if collection.nil?
+        collection
+      end
+    end
+  end
+end
+
+# :stopdoc:
+
+WillPaginate::ViewHelpers::LinkRenderer.class_eval do
+  protected
+  
+  def default_url_params
+    { :escape => false }
+  end
+  
+  def url(page)
+    @base_url_params ||= begin
+      url_params = base_url_params
+      merge_optional_params(url_params)
+      url_params
+    end
+    
+    url_params = @base_url_params.dup
+    add_current_page_param(url_params, page)
+    
+    @template.url_for(url_params)
+  end
+  
+  def base_url_params
+    url_params = default_url_params
+    # page links should preserve GET parameters
+    symbolized_update(url_params, @template.params) if get_request?
+    url_params
+  end
+  
+  def merge_optional_params(url_params)
+    symbolized_update(url_params, @options[:params]) if @options[:params]
+  end
+  
+  def add_current_page_param(url_params, page)
+    unless param_name.index(/[^\w-]/)
+      url_params[param_name.to_sym] = page
+    else
+      page_param = parse_query_parameters("#{param_name}=#{page}")
+      symbolized_update(url_params, page_param)
+    end
+  end
+  
+  def get_request?
+    @template.request.get?
+  end
+  
+  private
+  
+  def parse_query_parameters(params)
+    Rack::Utils.parse_nested_query(params)
+  end
+end