will_paginate 2.1.0 → 2.2.0

data/examples/pagination.sass

@@ -0,0 +1,91 @@
+.digg_pagination
+  :background white
+  a, span
+    :padding .2em .5em
+    :display block
+    :float left
+    :margin-right 1px
+  span.disabled
+    :color #999
+    :border 1px solid #DDD
+  span.current
+    :font-weight bold
+    :background #2E6AB1
+    :color white
+    :border 1px solid #2E6AB1
+  a
+    :text-decoration none
+    :color #105CB6
+    :border 1px solid #9AAFE5
+    &:hover, &:focus
+      :color #003
+      :border-color #003
+  .page_info
+    :background #2E6AB1
+    :color white
+    :padding .4em .6em
+    :width 22em
+    :margin-bottom .3em
+    :text-align center
+    b
+      :color #003
+      :background = #2E6AB1 + 60
+      :padding .1em .25em
+    
+  /* self-clearing method:
+  &:after
+    :content "."
+    :display block
+    :height 0
+    :clear both
+    :visibility hidden
+  * html &
+    :height 1%
+  *:first-child+html &
+    :overflow hidden
+
+.apple_pagination
+  :background #F1F1F1
+  :border 1px solid #E5E5E5
+  :text-align center
+  :padding 1em
+  a, span
+    :padding .2em .3em
+  span.disabled
+    :color #AAA
+  span.current
+    :font-weight bold
+    :background transparent url(apple-circle.gif) no-repeat 50% 50%
+  a
+    :text-decoration none
+    :color black
+    &:hover, &:focus
+      :text-decoration underline
+
+.flickr_pagination
+  :text-align center
+  :padding .3em
+  a, span
+    :padding .2em .5em
+  span.disabled
+    :color #AAA
+  span.current
+    :font-weight bold
+    :color #FF0084
+  a
+    :border 1px solid #DDDDDD
+    :color #0063DC
+    :text-decoration none
+    &:hover, &:focus
+      :border-color #003366
+      :background #0063DC
+      :color white
+  .page_info
+    :color #aaa
+    :padding-top .8em
+  .prev_page, .next_page
+    :border-width 2px
+  .prev_page
+    :margin-right 1em
+  .next_page
+    :margin-left 1em

data/init.rb

@@ -0,0 +1 @@
+require 'will_paginate'

data/lib/will_paginate.rb

@@ -20,6 +20,10 @@ module WillPaginate
       return if ActionView::Base.instance_methods.include? 'will_paginate'
       require 'will_paginate/view_helpers'
       ActionView::Base.class_eval { include ViewHelpers }
+
+      if defined?(ActionController::Base) and ActionController::Base.respond_to? :rescue_responses
+        ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
+      end
     end
     
     # mixes in WillPaginate::Finder in ActiveRecord::Base and classes that deal
@@ -29,28 +33,45 @@ module WillPaginate
       require 'will_paginate/finder'
       ActiveRecord::Base.class_eval { include Finder }
 
-      associations = ActiveRecord::Associations
-      collection = associations::AssociationCollection
-      
-      # to support paginating finders on associations, we have to mix in the
-      # method_missing magic from WillPaginate::Finder::ClassMethods to AssociationProxy
-      # subclasses, but in a different way for Rails 1.2.x and 2.0
-      (collection.instance_methods.include?(:create!) ?
-        collection : collection.subclasses.map(&:constantize)
-      ).push(associations::HasManyThroughAssociation).each do |klass|
+      # support pagination on associations
+      a = ActiveRecord::Associations
+      returning([ a::AssociationCollection ]) { |classes|
+        # detect http://dev.rubyonrails.org/changeset/9230
+        unless a::HasManyThroughAssociation.superclass == a::HasManyAssociation
+          classes << a::HasManyThroughAssociation
+        end
+      }.each do |klass|
         klass.class_eval do
           include Finder::ClassMethods
           alias_method_chain :method_missing, :paginate
         end
       end
     end
+
+    # Enable named_scope, a feature of Rails 2.1, even if you have older Rails
+    # (tested on Rails 2.0.2 and 1.2.6).
+    #
+    # You can pass +false+ for +patch+ parameter to skip monkeypatching
+    # *associations*. Use this if you feel that <tt>named_scope</tt> broke
+    # has_many, has_many :through or has_and_belongs_to_many associations in
+    # your app. By passing +false+, you can still use <tt>named_scope</tt> in
+    # your models, but not through associations.
+    def enable_named_scope(patch = true)
+      return if defined? ActiveRecord::NamedScope
+      require 'will_paginate/named_scope'
+      require 'will_paginate/named_scope_patch' if patch
+
+      ActiveRecord::Base.class_eval do
+        include WillPaginate::NamedScope
+      end
+    end
   end
 
   module Deprecation #:nodoc:
     extend ActiveSupport::Deprecation
 
     def self.warn(message, callstack = caller)
-      message = 'WillPaginate: ' + message.strip.gsub(/ {3,}/, ' ')
+      message = 'WillPaginate: ' + message.strip.gsub(/\s+/, ' ')
       behavior.call(message, callstack) if behavior && !silenced?
     end
 
@@ -60,4 +81,6 @@ module WillPaginate
   end
 end
 
-WillPaginate.enable if defined? ActiveRecord and defined? ActionView
+if defined?(Rails) and defined?(ActiveRecord) and defined?(ActionController)
+  WillPaginate.enable
+end

data/lib/will_paginate/array.rb

@@ -0,0 +1,16 @@
+require 'will_paginate/collection'
+
+# http://www.desimcadam.com/archives/8
+Array.class_eval do
+  def paginate(options = {})
+    raise ArgumentError, "parameter hash expected (got #{options.inspect})" unless Hash === options
+    
+    WillPaginate::Collection.create(
+        options[:page] || 1,
+        options[:per_page] || 30,
+        options[:total_entries] || self.length
+    ) { |pager|
+      pager.replace self[pager.offset, pager.per_page].to_a
+    }
+  end
+end

data/lib/will_paginate/collection.rb

@@ -1,11 +1,18 @@
-require 'will_paginate'
-
 module WillPaginate
-  # = OMG, invalid page number!
+  # = Invalid page number error
   # This is an ArgumentError raised in case a page was requested that is either
   # zero or negative number. You should decide how do deal with such errors in
   # the controller.
   #
+  # If you're using Rails 2, then this error will automatically get handled like
+  # 404 Not Found. The hook is in "will_paginate.rb":
+  #
+  #   ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
+  #
+  # If you don't like this, use your preffered method of rescuing exceptions in
+  # public from your controllers to handle this differently. The +rescue_from+
+  # method is a nice addition to Rails 2.
+  #
   # This error is *not* raised when a page further than the last page is
   # requested. Use <tt>WillPaginate::Collection#out_of_bounds?</tt> method to
   # check for those cases and manually deal with them as you see fit.
@@ -15,26 +22,34 @@ module WillPaginate
     end
   end
   
-  # Arrays returned from paginating finds are, in fact, instances of this.
-  # You may think of WillPaginate::Collection as an ordinary array with some
-  # extra properties. Those properties are used by view helpers to generate
+  # = The key to pagination
+  # Arrays returned from paginating finds are, in fact, instances of this little
+  # class. You may think of WillPaginate::Collection as an ordinary array with
+  # some extra properties. Those properties are used by view helpers to generate
   # correct page links.
   #
   # WillPaginate::Collection also assists in rolling out your own pagination
   # solutions: see +create+.
+  # 
+  # If you are writing a library that provides a collection which you would like
+  # to conform to this API, you don't have to copy these methods over; simply
+  # make your plugin/gem dependant on the "will_paginate" gem:
   #
+  #   gem 'will_paginate'
+  #   require 'will_paginate/collection'
+  #   
+  #   # now use WillPaginate::Collection directly or subclass it
   class Collection < Array
-    attr_reader :current_page, :per_page, :total_entries
+    attr_reader :current_page, :per_page, :total_entries, :total_pages
 
-    # Arguments to this constructor are the current page number, per-page limit
+    # Arguments to the constructor are the current page number, per-page limit
     # and the total number of entries. The last argument is optional because it
     # is best to do lazy counting; in other words, count *conditionally* after
     # populating the collection using the +replace+ method.
-    #
     def initialize(page, per_page, total = nil)
       @current_page = page.to_i
       raise InvalidPage.new(page, @current_page) if @current_page < 1
-      @per_page     = per_page.to_i
+      @per_page = per_page.to_i
       raise ArgumentError, "`per_page` setting cannot be less than 1 (#{@per_page} given)" if @per_page < 1
       
       self.total_entries = total if total
@@ -65,29 +80,25 @@ module WillPaginate
     #     end
     #   end
     #
+    # The Array#paginate API has since then changed, but this still serves as a
+    # fine example of WillPaginate::Collection usage.
     def self.create(page, per_page, total = nil, &block)
       pager = new(page, per_page, total)
       yield pager
       pager
     end
 
-    # The total number of pages.
-    def page_count
-      @total_pages
-    end
-
     # Helper method that is true when someone tries to fetch a page with a
     # larger number than the last page. Can be used in combination with flashes
     # and redirecting.
     def out_of_bounds?
-      current_page > page_count
+      current_page > total_pages
     end
 
     # Current offset of the paginated collection. If we're on the first page,
     # it is always 0. If we're on the 2nd page and there are 30 entries per page,
     # the offset is 30. This property is useful if you want to render ordinals
     # besides your records: simply start with offset + 1.
-    #
     def offset
       (current_page - 1) * per_page
     end
@@ -99,7 +110,7 @@ module WillPaginate
 
     # current_page + 1 or nil if there is no next page
     def next_page
-      current_page < page_count ? (current_page + 1) : nil
+      current_page < total_pages ? (current_page + 1) : nil
     end
 
     def total_entries=(number)
@@ -120,13 +131,15 @@ module WillPaginate
     # +total_entries+ and set it to a proper value if it's +nil+. See the example
     # in +create+.
     def replace(array)
-      returning super do
-        # The collection is shorter then page limit? Rejoice, because
-        # then we know that we are on the last page!
-        if total_entries.nil? and length > 0 and length < per_page
-          self.total_entries = offset + length
-        end
+      result = super
+      
+      # The collection is shorter then page limit? Rejoice, because
+      # then we know that we are on the last page!
+      if total_entries.nil? and length < per_page and (current_page == 1 or length > 0)
+        self.total_entries = offset + length
       end
+
+      result
     end
   end
 end

data/lib/will_paginate/core_ext.rb

@@ -1,5 +1,5 @@
-require 'will_paginate'
 require 'set'
+require 'will_paginate/array'
 
 unless Hash.instance_methods.include? 'except'
   Hash.class_eval do
@@ -30,51 +30,3 @@ unless Hash.instance_methods.include? 'slice'
     end
   end
 end
-
-unless Hash.instance_methods.include? 'rec_merge!'
-  Hash.class_eval do
-    # Same as Hash#merge!, but recursively merges sub-hashes
-    # (stolen from Haml)
-    def rec_merge!(other)
-      other.each do |key, other_value|
-        value = self[key]
-        if value.is_a?(Hash) and other_value.is_a?(Hash)
-          value.rec_merge! other_value
-        else
-          self[key] = other_value
-        end
-      end
-      self
-    end
-  end
-end
-
-require 'will_paginate/collection'
-
-unless Array.instance_methods.include? 'paginate'
-  # http://www.desimcadam.com/archives/8
-  Array.class_eval do
-    def paginate(options_or_page = {}, per_page = nil)
-      if options_or_page.nil? or Fixnum === options_or_page
-        if defined? WillPaginate::Deprecation
-          WillPaginate::Deprecation.warn <<-DEPR
-            Array#paginate now conforms to the main, ActiveRecord::Base#paginate API.  You should \
-            call it with a parameters hash (:page, :per_page).  The old API (numbers as arguments) \
-            has been deprecated and is going to be unsupported in future versions of will_paginate.
-          DEPR
-        end
-        page = options_or_page
-        options = {}
-      else
-        options = options_or_page
-        page = options[:page]
-        raise ArgumentError, "wrong number of arguments (1 hash or 2 Fixnums expected)" if per_page
-        per_page = options[:per_page]
-      end
-
-      WillPaginate::Collection.create(page || 1, per_page || 30, options[:total_entries] || size) do |pager|
-        pager.replace self[pager.offset, pager.per_page].to_a
-      end
-    end
-  end
-end

data/lib/will_paginate/finder.rb

@@ -2,7 +2,7 @@ require 'will_paginate/core_ext'
 
 module WillPaginate
   # A mixin for ActiveRecord::Base. Provides +per_page+ class method
-  # and makes +paginate+ finders possible with some method_missing magic.
+  # and hooks things up to provide paginating finders.
   #
   # Find out more in WillPaginate::Finder::ClassMethods
   #
@@ -18,9 +18,9 @@ module WillPaginate
 
     # = Paginating finders for ActiveRecord models
     # 
-    # WillPaginate adds +paginate+ and +per_page+ methods to ActiveRecord::Base
-    # class methods and associations. It also hooks into +method_missing+ to
-    # intercept pagination calls to dynamic finders such as
+    # 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).
     # 
@@ -85,6 +85,31 @@ module WillPaginate
           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 http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord where
+      # Jamis Buck describes this 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
       
       # 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

data/lib/will_paginate/named_scope.rb

@@ -0,0 +1,132 @@
+## stolen from: http://dev.rubyonrails.org/browser/trunk/activerecord/lib/active_record/named_scope.rb?rev=9084
+
+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:
+    #
+    #   Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)
+    #
+    # 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 :all
+        named_scope :scoped, lambda { |scope| scope }
+      end
+    end
+
+    module ClassMethods
+      def scopes #:nodoc:
+        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 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
+      #
+      def named_scope(name, options = {}, &block)
+        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 #:nodoc:
+      attr_reader :proxy_scope, :proxy_options
+      [].methods.each { |m| delegate m, :to => :proxy_found unless m =~ /(^__|^nil\?|^send|class|extend|find|count|sum|average|maximum|minimum|paginate)/ }
+      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
+
+      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