will_paginate 2.3.16 → 3.0.pre

data/CHANGELOG.rdoc

@@ -1,81 +1,25 @@
-= 2.3.16, released 2011-08-09
-
-* added global <tt>WillPaginate.per_page = 30</tt> setting
-* added i18n capabilities to previous/next labels and page_entries_info
-* page_entries_info ":entry_name" parameter is now renamed to ":model"
-* new option: page_entries_info(:html => false)
-* fix page_entries_info output with rails_xss
-* raise an InvalidPage exception if the calculated offset is bigger than BIGINT
-* fixed bugs with Rails 1.2.6
-
-= 2.3.15, released 2010-09-09
-
-* ensure respond_to? works as expected considering methods that begin with 'paginate'
-* fix counting in pagination when Integer has length method (Ruby Facets)
-* stop using deprecated Object#returning
-* fixed has_many :through in combination with `:uniq` for Postgres and SQLite3
-
-= 2.3.14, released 2010-05-26
-= 2.3.13, released 2010-05-26
-
-* better rails_xss compatibility
-
-= 2.3.12, released 2009-12-01
-
-* make view helpers "HTML safe" for Rails 2.3.5 with rails_xss plugin
-
-= 2.3.11, released 2009-06-02
-
-* fix `enable_actionpack`
-
-= 2.3.10, released 2009-05-21
-
-* count_by_sql: don't use table alias with any adapters starting with "oracle"
-* Add back "AS count_table" alias to `paginate_by_sql` counter SQL
-
-= 2.3.9, released 2009-05-29
-
-* remove "AS count_table" alias from `paginate_by_sql` counter SQL
-* Rails 2.3.2 compat: monkeypatch Rails issue #2189 (count breaks has_many :through)
-* fix generation of page URLs that contain the "@" character
-* check for method existance in a ruby 1.8- and 1.9-compatible way
-* load will_paginate view helpers even if ActiveRecord is not loaded
-
-== 2.3.8, released 2009-03-09
-
-* Rails 2.3 compat: query parameter parsing with Rack
-
-== 2.3.7, released 2009-02-09
-
-* Removed all unnecessary &block variables since they cause serious memory damage and lots of subsequent gc runs.
-
-== 2.3.6, released 2008-10-26
-
-* Rails 2.2 fix: stop using `extract_attribute_names_from_match` inernal AR method, it no longer exists
-
-== 2.3.5, released 2008-10-07
-
-* update the backported named_scope implementation for Rails versions older than 2.1
-* break out of scope of paginated_each() yielded block when used on named scopes
-* fix paginate(:from)
-
-== 2.3.4, released 2008-09-16
-
-* Removed gem dependency to Active Support (causes trouble with vendored rails).
-* Rails 2.1: fix a failing test and a deprecation warning.
-* Cope with scoped :select when counting.
-
-== 2.3.3, released 2008-08-29
-
-* Ensure that paginate_by_sql doesn't change the original SQL query.
-* RDoc love (now live at http://gitrdoc.com/mislav/will_paginate/tree/master)
-* Rename :prev_label to :previous_label for consistency. old name still functions but is deprecated
-* ActiveRecord 2.1: Remove :include option from count_all query when it's possible.
-
-== 2.3.2, released 2008-05-16
-
-* Fixed LinkRenderer#stringified_merge by removing "return" from iterator block
-* Ensure that 'href' values in pagination links are escaped URLs
+== "agnostic" branch
+
+* added Sequel support
+* added an initialization hook for Merb
+* refactored URL generation
+* BACKWARDS INCOMPATIBLE: refactored LinkRenderer; also markup changes
+    <span class="current">1</span> is now <em>1</em>
+    a.prev_page -> a.previous_page (for consistency)
+* "prev_label" -> "previous_label"
+* ported view tests to specs
+* setup Autotest
+* added per_page=(limit) attribute writer to set default per_page
+* Remove :include option from count_all query when possible (Rails 2.1)
+* added WP::ViewHelpers::ActionView and LinkRenderer
+* specs for ViewHelpers::Base and LinkRendererBase
+* created LinkRendererBase that implements windowed visible page numbers logic
+* created WP::ViewHelpers::Base abstract module that implements generic view helpers
+* ported finder tests to specs
+* added WP::Finders::DataMapper
+* added WP::Finders::ActiveRecord mixin for ActiveRecord::Base
+* created WP::Finders::Base abstract module that implements generic pagination logic
+* removed dependency to ActiveSupport
 
 == 2.3.1, released 2008-05-04
 
@@ -106,14 +50,14 @@
     gem install mislav-will_paginate
     
 * extract reusable pagination testing stuff into WillPaginate::View
-* rethink the page URL construction mechanizm to be more bulletproof when
+* rethink the page URL construction mechanism to be more bulletproof when
   combined with custom routing for page parameter
 * test that anchor parameter can be used in pagination links
 
 == 2.2.2, released 2008-04-21
 
 * Add support for page parameter in custom routes like "/foo/page/2"
-* Change output of "page_entries_info" on single-page collection and erraneous
+* Change output of "page_entries_info" on single-page collection and erroneous
   output with empty collection as reported by Tim Chater
   
 == 2.2.1, released 2008-04-08

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007 PJ Hyett and Mislav Marohnić
+Copyright (c) 2009 Mislav Marohnić
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of 
 this software and associated documentation files (the "Software"), to deal in 

data/README.rdoc

@@ -0,0 +1,125 @@
+= The will_paginate Ruby library
+
+Pagination is just limiting the number of records loaded and displayed. Why should you let it get in
+your way while developing?
+
+This is how you paginate on an ActiveRecord model:
+
+  Post.paginate :page => 1, :order => 'created_at DESC'
+
+Most of the time it's as simple as replacing "find" with "paginate" and specifying the page you want.
+
+Some resources to get you started:
+
+* The {will_paginate project page}[http://mislav.github.com/will_paginate/];
+* Your mind reels with questions? Join our {Google group}[http://groups.google.com/group/will_paginate];
+* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs];
+* {Watch the will_paginate screencast}[http://railscasts.com/episodes/51] by Ryan Bates.
+
+== I'm not using Rails; can I still use will_paginate?
+
+Absolutely -- although will_paginate started off as a Rails plugin, now it is a <em>completely
+framework-agnostic</em> library with support for Rails and Merb built-in. The core library doesn't
+have any dependences and you can safely use it in any Ruby code.
+
+When will_paginate is loaded in an environment where ActiveRecord and ActionView are present, it
+automatically hooks into these frameworks to provide easy pagination on your models and in your
+views. The same mechanism works for Merb applications, too. But, if no known framework is present
+then you have absolute control over what parts of will_paginate do you want to load and where you want
+them mixed in.
+
+
+== Installation
+
+The recommended way is that you get the gem hosted on {gems.github.com}[http://gems.github.com/]:
+
+  gem install mislav-will_paginate
+
+In <b>Rails 2.1</b>, add a gem dependency:
+
+  # for Rails 2.1 and newer
+  config.gem 'mislav-will_paginate', :lib => 'will_paginate', :version => '~> 3.0'
+
+If you're using Rails 2.0 or older, or any other Ruby framework, just add a simple require to a file
+that initializes your application. For example, in Rails you would put this at the end of
+"config/environment.rb".
+
+  gem 'mislav-will_paginate', '~> 3.0'
+  require 'will_paginate'
+
+That's it. Remember to install the gem on <strong>all</strong> machines that you are deploying to.
+
+<i>There are extensive {installation
+instructions}[http://github.com/mislav/will_paginate/wikis/installation] on {the
+wiki}[http://github.com/mislav/will_paginate/wikis].</i>
+
+
+== Example usage
+
+Typical usage involves a paginating find in the controller:
+  
+  @posts = Post.paginate :page => params[:page], :order => 'updated_at DESC'
+
+It's true: +paginate+ works just like +find+ -- it just doesn't fetch all the records. Don't forget
+to tell it which page you want, or it will complain! Read more in WillPaginate::Finders.
+
+Render the posts in your view like you would normally do, and when you need to render pagination,
+just stick this in:
+
+  <%= will_paginate @posts %>
+
+You're done. Read more in WillPaginate::ViewHelpers::Base.
+
+How does it know how much items to fetch per page? It asks your model by calling its
++per_page+ class method. You can define it like this:
+
+  class Post < ActiveRecord::Base
+    self.per_page = 50
+  end
+
+... or don't worry about it at all. WillPaginate defines it to be <strong>30</strong> by default. You can
+always specify the count explicitly when calling +paginate+:
+
+  Post.paginate :page => params[:page], :per_page => 50
+
+The +paginate+ finder wraps the original finder and returns your result set that now has some new
+properties. You can use the collection as you would use any other array. WillPaginate view helpers
+also need that collection object to be able to render pagination:
+
+  <ol>
+    <% for post in @posts -%>
+      <li>Render `post` in some nice way.</li>
+    <% end -%>
+  </ol>
+
+  <p>Now let's render us some pagination!</p>
+  <%= will_paginate @posts %>
+
+
+== Authors and credits
+
+The original author of will_paginate was PJ Hyett, who later handed over development to Mislav
+Marohnić. (The library was completely rewritten since then.)
+
+All these people helped making will_paginate what it is now with their code contributions or just
+simply awesome ideas:
+
+Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, Mike Garey, Bence Golda, Matt Aimonetti,
+Charles Brian Quinn, Desi McAdam, James Coglan, Matijs van Zuijlen, Maria, Brendan Ribera, Todd
+Willey, Bryan Helmkamp, Jan Berkel, Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris
+Eppstein, Brandon Arbini, Denis Barushev, Paul Barry, Ben Pickles, Ken Collins, Lida Tang and Pieter
+Noordhuis.
+
+
+== Usable pagination in the UI
+
+There are example CSS styles to get you started on the will_paginate project page.
+
+More reading about pagination as design pattern:
+
+* {Pagination 101}[http://kurafire.net/log/archive/2007/06/22/pagination-101];
+* {Pagination gallery}[http://www.smashingmagazine.com/2007/11/16/pagination-gallery-examples-and-good-practices/] featured on Smashing Magazine;
+* {Pagination design pattern}[http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination] on Yahoo Design Pattern Library.
+
+Want to discuss, request features, ask questions? Join the {Google
+group}[http://groups.google.com/group/will_paginate].

data/Rakefile

@@ -1,28 +1,32 @@
-require 'rake/testtask'
+require 'rake/rdoctask'
 
-desc 'Default: run unit tests.'
-task :default => :test
+load 'spec/tasks.rake'
 
-desc 'Test the will_paginate plugin.'
-Rake::TestTask.new(:test) do |t|
-  if ENV['DB'] and ENV['DB'] != 'sqlite3'
-    t.pattern = %w[test/finder_test.rb]
-  else
-    t.pattern = 'test/**/*_test.rb'
-  end
-  t.libs << 'test'
-end
+desc 'Default: run specs.'
+task :default => :spec
 
-namespace :test do ||
-  desc 'Test only Rails integration'
-  Rake::TestTask.new(:rails) do |t|
-    t.pattern = %w[test/finder_test.rb test/view_test.rb]
-    t.libs << 'test'
-  end
+desc 'Generate RDoc documentation for the will_paginate plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG.rdoc').
+    include('lib/**/*.rb').
+    exclude('lib/will_paginate/finders/active_record/named_scope*').
+    exclude('lib/will_paginate/finders/sequel.rb').
+    exclude('lib/will_paginate/view_helpers/merb.rb').
+    exclude('lib/will_paginate/deprecation.rb').
+    exclude('lib/will_paginate/core_ext.rb').
+    exclude('lib/will_paginate/version.rb')
+  
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "will_paginate documentation"
+  
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--inline-source' << '--charset=UTF-8'
+  rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+end
 
-  desc 'Test only ActiveRecord integration'
-  Rake::TestTask.new(:db) do |t|
-    t.pattern = %w[test/finder_test.rb]
-    t.libs << 'test'
+task :website do
+  Dir.chdir('website') do
+    %x(haml index.haml index.html)
+    %x(sass pagination.sass pagination.css)
   end
 end

data/lib/will_paginate/array.rb

@@ -1,15 +1,32 @@
 require 'will_paginate/collection'
-require 'will_paginate/per_page'
 
-# http://www.desimcadam.com/archives/8
-Array.class_eval do
+class Array
+  # Paginates a static array (extracting a subset of it). The result is a
+  # WillPaginate::Collection instance, which is an array with a few more
+  # properties about its paginated state.
+  #
+  # Parameters:
+  # * <tt>:page</tt> - current page, defaults to 1
+  # * <tt>:per_page</tt> - limit of items per page, defaults to 30
+  # * <tt>:total_entries</tt> - total number of items in the array, defaults to
+  #   <tt>array.length</tt> (obviously)
+  #
+  # Example:
+  #   arr = ['a', 'b', 'c', 'd', 'e']
+  #   paged = arr.paginate(:per_page => 2)      #->  ['a', 'b']
+  #   paged.total_entries                       #->  5
+  #   arr.paginate(:page => 2, :per_page => 2)  #->  ['c', 'd']
+  #   arr.paginate(:page => 3, :per_page => 2)  #->  ['e']
+  #
+  # This method was originally {suggested by Desi
+  # McAdam}[http://www.desimcadam.com/archives/8] and later proved to be the
+  # most useful method of will_paginate library.
   def paginate(options = {})
     raise ArgumentError, "parameter hash expected (got #{options.inspect})" unless Hash === options
-    page     = options[:page] || 1
-    per_page = options[:per_page] || WillPaginate.per_page
-    total    = options[:total_entries] || self.length
-
-    WillPaginate::Collection.create(page, per_page, total) do |pager|
+    
+    WillPaginate::Collection.create options[:page] || 1,
+                                    options[:per_page] || 30,
+                                    options[:total_entries] || self.length do |pager|
       pager.replace self[pager.offset, pager.per_page].to_a
     end
   end

data/lib/will_paginate/collection.rb

@@ -1,5 +1,3 @@
-require 'will_paginate/per_page'
-
 module WillPaginate
   # = Invalid page number error
   # This is an ArgumentError raised in case a page was requested that is either
@@ -19,24 +17,8 @@ module WillPaginate
   # requested. Use <tt>WillPaginate::Collection#out_of_bounds?</tt> method to
   # check for those cases and manually deal with them as you see fit.
   class InvalidPage < ArgumentError
-    # a value bigger than this would result in invalid SQL queries
-    BIGINT = 9223372036854775807
-
-    def self.validate(page_value, per_page_value)
-      page = page_value.to_i
-      raise self.new(page_value, page) if page < 1
-      per_page = per_page_value.to_i
-      offset = (page - 1) * per_page
-      raise self, "invalid offset: #{offset.inspect}" if offset < 0 or offset > BIGINT
-      [page, per_page]
-    end
-
-    def initialize(value, page_num = nil)
-      if page_num
-        super "#{value.inspect} given as value, which translates to '#{page_num}' as page number"
-      else
-        super value
-      end
+    def initialize(page, page_num) #:nodoc:
+      super "#{page.inspect} given as value, which translates to '#{page_num}' as page number"
     end
   end
   
@@ -51,10 +33,12 @@ module WillPaginate
   # 
   # 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 this library and do:
+  # make your plugin/gem dependant on the "will_paginate" gem:
   #
+  #   gem 'will_paginate'
   #   require 'will_paginate/collection'
-  #   # WillPaginate::Collection is now available for use
+  #   
+  #   # now use WillPaginate::Collection directly or subclass it
   class Collection < Array
     attr_reader :current_page, :per_page, :total_entries, :total_pages
 
@@ -62,8 +46,12 @@ module WillPaginate
     # 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 = WillPaginate.per_page, total = nil)
-      @current_page, @per_page = InvalidPage.validate(page, per_page)
+    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
+      raise ArgumentError, "`per_page` setting cannot be less than 1 (#{@per_page} given)" if @per_page < 1
+      
       self.total_entries = total if total
     end
 
@@ -94,7 +82,7 @@ module WillPaginate
     #
     # 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)
+    def self.create(page, per_page, total = nil, &block)
       pager = new(page, per_page, total)
       yield pager
       pager
@@ -110,7 +98,7 @@ module WillPaginate
     # 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
-    # side by side with records in the view: simply start with offset + 1.
+    # besides your records: simply start with offset + 1.
     def offset
       (current_page - 1) * per_page
     end
@@ -124,8 +112,7 @@ module WillPaginate
     def next_page
       current_page < total_pages ? (current_page + 1) : nil
     end
-    
-    # sets the <tt>total_entries</tt> property and calculates <tt>total_pages</tt>
+
     def total_entries=(number)
       @total_entries = number.to_i
       @total_pages   = (@total_entries / per_page.to_f).ceil

data/lib/will_paginate/core_ext.rb

@@ -12,6 +12,8 @@ class Array
   end
 end
 
+## everything below copied from ActiveSupport so we don't depend on it ##
+
 unless Hash.instance_methods.include_method? :except
   Hash.class_eval do
     # Returns a new hash without the given keys.
@@ -41,3 +43,27 @@ unless Hash.instance_methods.include_method? :slice
     end
   end
 end
+
+unless String.instance_methods.include_method? :constantize
+  String.class_eval do
+    def constantize
+      unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
+        raise NameError, "#{self.inspect} is not a valid constant name!"
+      end
+
+      Object.module_eval("::#{$1}", __FILE__, __LINE__)
+    end
+  end
+end
+
+unless String.instance_methods.include_method? :underscore
+  String.class_eval do
+    def underscore
+      self.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+  end
+end

data/lib/will_paginate/deprecation.rb

@@ -0,0 +1,50 @@
+# borrowed from ActiveSupport::Deprecation
+module WillPaginate
+  module Deprecation
+    def self.debug() @debug; end
+    def self.debug=(value) @debug = value; end
+    self.debug = false
+
+    # Choose the default warn behavior according to Rails.env.
+    # Ignore deprecation warnings in production.
+    BEHAVIORS = {
+      'test'        => Proc.new { |message, callstack|
+                         $stderr.puts(message)
+                         $stderr.puts callstack.join("\n  ") if debug
+                       },
+      'development' => Proc.new { |message, callstack|
+                         logger = defined?(::RAILS_DEFAULT_LOGGER) ? ::RAILS_DEFAULT_LOGGER : Logger.new($stderr)
+                         logger.warn message
+                         logger.debug callstack.join("\n  ") if debug
+                       }
+    }
+
+    def self.warn(message, callstack = caller)
+      if behavior
+        message = 'WillPaginate: ' + message.strip.gsub(/\s+/, ' ')
+        behavior.call(message, callstack)
+      end
+    end
+
+    def self.default_behavior
+      if defined?(::Rails)
+        BEHAVIORS[::Rails.env.to_s]
+      else
+        BEHAVIORS['test']
+      end
+    end
+
+    # Behavior is a block that takes a message argument.
+    def self.behavior() @behavior; end
+    def self.behavior=(value) @behavior = value; end
+    self.behavior = default_behavior
+
+    def self.silence
+      old_behavior = self.behavior
+      self.behavior = nil
+      yield
+    ensure
+      self.behavior = old_behavior
+    end
+  end
+end