agnostic-will_paginate 3.0.0

data/lib/will_paginate/finders/active_record/named_scope.rb

@@ -0,0 +1,170 @@
+module WillPaginate
+  # This is a feature backported from Rails 2.1 because of its usefullness not only with will_paginate,
+  # but in other aspects when managing complex conditions that you want to be reusable.
+  module NamedScope
+    # All subclasses of ActiveRecord::Base have two named_scopes:
+    # * <tt>all</tt>, which is similar to a <tt>find(:all)</tt> query, and
+    # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt>
+    #
+    # These anonymous scopes tend to be useful when procedurally generating complex queries, where passing
+    # intermediate values (scopes) around as first-class objects is convenient.
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        named_scope :scoped, lambda { |scope| scope }
+      end
+    end
+
+    module ClassMethods
+      def scopes
+        read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
+      end
+
+      # Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query,
+      # such as <tt>:conditions => {:color => :red}, :select => 'shirts.*', :include => :washing_instructions</tt>.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :red, :conditions => {:color => 'red'}
+      #     named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true]
+      #   end
+      # 
+      # The above calls to <tt>named_scope</tt> define class methods <tt>Shirt.red</tt> and <tt>Shirt.dry_clean_only</tt>. <tt>Shirt.red</tt>, 
+      # in effect, represents the query <tt>Shirt.find(:all, :conditions => {:color => 'red'})</tt>.
+      #
+      # Unlike Shirt.find(...), however, the object returned by <tt>Shirt.red</tt> is not an Array; it resembles the association object
+      # constructed by a <tt>has_many</tt> declaration. For instance, you can invoke <tt>Shirt.red.find(:first)</tt>, <tt>Shirt.red.count</tt>,
+      # <tt>Shirt.red.find(:all, :conditions => {:size => 'small'})</tt>. Also, just
+      # as with the association objects, name scopes acts like an Array, implementing Enumerable; <tt>Shirt.red.each(&block)</tt>,
+      # <tt>Shirt.red.first</tt>, and <tt>Shirt.red.inject(memo, &block)</tt> all behave as if Shirt.red really were an Array.
+      #
+      # These named scopes are composable. For instance, <tt>Shirt.red.dry_clean_only</tt> will produce all shirts that are both red and dry clean only.
+      # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
+      # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
+      #
+      # All scopes are available as class methods on the ActiveRecord::Base descendent upon which the scopes were defined. But they are also available to
+      # <tt>has_many</tt> associations. If,
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :shirts
+      #   end
+      #
+      # then <tt>elton.shirts.red.dry_clean_only</tt> will return all of Elton's red, dry clean
+      # only shirts.
+      #
+      # Named scopes can also be procedural.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :colored, lambda { |color|
+      #       { :conditions => { :color => color } }
+      #     }
+      #   end
+      #
+      # In this example, <tt>Shirt.colored('puce')</tt> finds all puce shirts.
+      #
+      # Named scopes can also have extensions, just as with <tt>has_many</tt> declarations:
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :red, :conditions => {:color => 'red'} do
+      #       def dom_id
+      #         'red_shirts'
+      #       end
+      #     end
+      #   end
+      #
+      #
+      # For testing complex named scopes, you can examine the scoping options using the
+      # <tt>proxy_options</tt> method on the proxy itself.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :colored, lambda { |color|
+      #       { :conditions => { :color => color } }
+      #     }
+      #   end
+      #
+      #   expected_options = { :conditions => { :colored => 'red' } }
+      #   assert_equal expected_options, Shirt.colored('red').proxy_options
+      def named_scope(name, options = {}, &block)
+        name = name.to_sym
+        scopes[name] = lambda do |parent_scope, *args|
+          Scope.new(parent_scope, case options
+            when Hash
+              options
+            when Proc
+              options.call(*args)
+          end, &block)
+        end
+        (class << self; self end).instance_eval do
+          define_method name do |*args|
+            scopes[name].call(self, *args)
+          end
+        end
+      end
+    end
+    
+    class Scope
+      attr_reader :proxy_scope, :proxy_options
+
+      [].methods.each do |m|
+        unless m =~ /(^__|^nil\?|^send|^object_id$|class|extend|^find$|count|sum|average|maximum|minimum|paginate|first|last|empty\?|respond_to\?)/
+          delegate m, :to => :proxy_found
+        end
+      end
+
+      delegate :scopes, :with_scope, :to => :proxy_scope
+
+      def initialize(proxy_scope, options, &block)
+        [options[:extend]].flatten.each { |extension| extend extension } if options[:extend]
+        extend Module.new(&block) if block_given?
+        @proxy_scope, @proxy_options = proxy_scope, options.except(:extend)
+      end
+
+      def reload
+        load_found; self
+      end
+
+      def first(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.first(*args)
+        else
+          find(:first, *args)
+        end
+      end
+
+      def last(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.last(*args)
+        else
+          find(:last, *args)
+        end
+      end
+
+      def empty?
+        @found ? @found.empty? : count.zero?
+      end
+
+      def respond_to?(method, include_private = false)
+        super || @proxy_scope.respond_to?(method, include_private)
+      end
+
+      protected
+      def proxy_found
+        @found || load_found
+      end
+
+      private
+      def method_missing(method, *args, &block)
+        if scopes.include?(method)
+          scopes[method].call(self, *args)
+        else
+          with_scope :find => proxy_options do
+            proxy_scope.send(method, *args, &block)
+          end
+        end
+      end
+
+      def load_found
+        @found = find(:all)
+      end
+    end
+  end
+end

data/lib/will_paginate/finders/active_record/named_scope_patch.rb

@@ -0,0 +1,39 @@
+## based on http://dev.rubyonrails.org/changeset/9084
+
+ActiveRecord::Associations::AssociationProxy.class_eval do
+  protected
+  def with_scope(*args, &block)
+    @reflection.klass.send :with_scope, *args, &block
+  end
+end
+
+[ ActiveRecord::Associations::AssociationCollection,
+    ActiveRecord::Associations::HasManyThroughAssociation ].each do |klass|
+  klass.class_eval do
+    protected
+    alias :method_missing_without_scopes :method_missing_without_paginate
+    def method_missing_without_paginate(method, *args, &block)
+      if @reflection.klass.scopes.include?(method)
+        @reflection.klass.scopes[method].call(self, *args, &block)
+      else
+        method_missing_without_scopes(method, *args, &block)
+      end
+    end
+  end
+end
+
+# Rails 1.2.6
+ActiveRecord::Associations::HasAndBelongsToManyAssociation.class_eval do
+  protected
+  def method_missing(method, *args, &block)
+    if @target.respond_to?(method) || (!@reflection.klass.respond_to?(method) && Class.respond_to?(method))
+      super
+    elsif @reflection.klass.scopes.include?(method)
+      @reflection.klass.scopes[method].call(self, *args)
+    else
+      @reflection.klass.with_scope(:find => { :conditions => @finder_sql, :joins => @join_sql, :readonly => false }) do
+        @reflection.klass.send(method, *args, &block)
+      end
+    end
+  end
+end if ActiveRecord::Base.respond_to? :find_first

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,22 @@
+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/version.rb

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

data/lib/will_paginate/view_helpers.rb

@@ -0,0 +1,42 @@
+require 'will_paginate/deprecation'
+
+module WillPaginate
+  # = Will Paginate view helpers
+  #
+  # The main view helper is +will_paginate+. It renders the pagination links
+  # for the given collection. The helper itself is lightweight and serves only
+  # as a wrapper around LinkRenderer instantiation; the renderer then does
+  # all the hard work of generating the HTML.
+  # 
+  # Read more in WillPaginate::ViewHelpers::Base
+  module ViewHelpers
+    # ==== Global options for helpers
+    #
+    # Options for pagination helpers are optional and get their default values
+    # from the WillPaginate::ViewHelpers.pagination_options hash. You can write
+    # to this hash to override default options on the global level:
+    #
+    #   WillPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous page'
+    #
+    # By putting this into your environment.rb you can easily translate link
+    # texts to previous and next pages, as well as override some other defaults
+    # to your liking.
+    def self.pagination_options() @pagination_options; end
+    # Overrides the default +pagination_options+
+    def self.pagination_options=(value) @pagination_options = value; end
+    
+    self.pagination_options = {
+      :class          => 'pagination',
+      :previous_label => '← Previous',
+      :next_label     => 'Next →',
+      :inner_window   => 4, # links around the current page
+      :outer_window   => 1, # links around beginning and end
+      :separator      => ' ', # single space is friendly to spiders and non-graphic browsers
+      :param_name     => :page,
+      :params         => nil,
+      :renderer       => 'WillPaginate::ViewHelpers::LinkRenderer',
+      :page_links     => true,
+      :container      => true
+    }
+  end
+end