will_paginate 2.3.17 → 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.rb

@@ -1,97 +1,23 @@
-require 'active_support'
-require 'will_paginate/core_ext'
+require 'will_paginate/deprecation'
 
 # = You *will* paginate!
 #
-# First read about WillPaginate::Finder::ClassMethods, then see
+# First read about WillPaginate::Finders::Base, then see
 # WillPaginate::ViewHelpers. The magical array you're handling in-between is
 # WillPaginate::Collection.
 #
 # Happy paginating!
 module WillPaginate
-  class << self
-    # shortcut for <tt>enable_actionpack</tt> and <tt>enable_activerecord</tt> combined
-    def enable
-      enable_actionpack
-      enable_activerecord
-    end
-    
-    # hooks WillPaginate::ViewHelpers into ActionView::Base
-    def enable_actionpack
-      return if ActionView::Base.instance_methods.include_method? :will_paginate
-      require 'will_paginate/view_helpers'
-      ActionView::Base.send :include, ViewHelpers
-
-      if defined?(ActionController::Base) and ActionController::Base.respond_to? :rescue_responses
-        ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
-      end
-    end
-    
-    # hooks WillPaginate::Finder into ActiveRecord::Base and classes that deal
-    # with associations
-    def enable_activerecord
-      return if ActiveRecord::Base.respond_to? :paginate
-      require 'will_paginate/finder'
-      ActiveRecord::Base.send :include, Finder
-
-      # support pagination on associations
-      a = ActiveRecord::Associations
-      klasses = [ a::AssociationCollection ]
-      # detect http://dev.rubyonrails.org/changeset/9230
-      unless a::HasManyThroughAssociation.superclass == a::HasManyAssociation
-        klasses << a::HasManyThroughAssociation
-      end
-
-      klasses.each do |klass|
-        klass.send :include, Finder::ClassMethods
-        klass.class_eval { alias_method_chain :method_missing, :paginate }
-      end
-      
-      # monkeypatch Rails ticket #2189: "count breaks has_many :through"
-      ActiveRecord::Base.class_eval do
-        protected
-        def self.construct_count_options_from_args(*args)
-          result = super
-          result[0] = '*' if result[0].is_a?(String) and result[0] =~ /\.\*$/
-          result
-        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.send :include, WillPaginate::NamedScope
-    end
-  end
-
-  module Deprecation # :nodoc:
-    extend ActiveSupport::Deprecation
-
-    def self.warn(message, callstack = caller)
-      message = 'WillPaginate: ' + message.strip.gsub(/\s+/, ' ')
-      ActiveSupport::Deprecation.warn(message, callstack)
-    end
-  end
 end
 
-if defined? Rails
-  WillPaginate.enable_activerecord if defined? ActiveRecord
-  WillPaginate.enable_actionpack if defined? ActionController
+if defined?(::Rails::Railtie)
+  require 'will_paginate/railtie'
 end
 
-# load default translations only for newer versions of I18n
-if defined? I18n and not defined? I18n::Backend::Simple::MATCH
-  require 'will_paginate/i18n'
-  I18n.load_path.unshift(*WillPaginate::I18n.load_path)
+if defined?(::Merb::Plugins)
+  require 'will_paginate/view_helpers/merb'
+  # auto-load the right ORM adapter
+  if adapter = { :datamapper => 'data_mapper', :activerecord => 'active_record', :sequel => 'sequel' }[Merb.orm]
+    require "will_paginate/finders/#{adapter}"
+  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