will_paginate 2.3.15 → 2.3.16

data/CHANGELOG.rdoc

@@ -1,3 +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

data/README.md

@@ -0,0 +1,53 @@
+# will_paginate
+
+will_paginate v2.3 is a pagination plugin for Rails and Active Record.
+
+Installation:
+
+~~~ ruby
+## environment.rb
+Rails::Initializer.run do |config|
+  config.gem 'will_paginate', :version => '~> 2.3.16'
+end
+~~~
+
+See [installation instructions][install] on the wiki for more info.
+
+
+## Basic will_paginate use
+
+~~~ ruby
+## perform a paginated query:
+@posts = Post.paginate(:page => params[:page])
+
+# or, use an explicit "per page" limit:
+Post.paginate(:page => params[:page], :per_page => 30)
+
+## render page links in the view:
+<%= will_paginate @posts %>
+~~~
+
+And that's it! You're done. You just need to add some CSS styles to [make those pagination links prettier][css].
+
+You can customize the default "per_page" value:
+
+~~~ ruby
+# for the Post model
+class Post
+  self.per_page = 10
+end
+
+# set per_page globally
+WillPaginate.per_page = 10
+~~~
+
+See [the wiki][wiki] for more documentation. [Ask on the group][group] if you have usage questions. [Report bugs][issues] on GitHub.
+
+Happy paginating.
+
+
+[wiki]: https://github.com/mislav/will_paginate/wiki
+[install]: https://github.com/mislav/will_paginate/wiki/Installation "will_paginate installation"
+[group]: http://groups.google.com/group/will_paginate "will_paginate discussion and support group"
+[issues]: https://github.com/mislav/will_paginate/issues
+[css]: http://mislav.uniqpath.com/will_paginate/

data/Rakefile

@@ -1,53 +1,28 @@
-require 'rubygems'
-begin
-  hanna_dir = '/Users/mislav/Projects/Hanna/lib'
-  $:.unshift hanna_dir if File.exists? hanna_dir
-  require 'hanna/rdoctask'
-rescue LoadError
-  require 'rake'
-  require 'rake/rdoctask'
-end
-load 'test/tasks.rake'
+require 'rake/testtask'
 
 desc 'Default: run unit tests.'
 task :default => :test
 
-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/named_scope*').
-    exclude('lib/will_paginate/array.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/'
+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 %{Update ".manifest" with the latest list of project filenames. Respect\
-.gitignore by excluding everything that git ignores. Update `files` and\
-`test_files` arrays in "*.gemspec" file if it's present.}
-task :manifest do
-  list = `git ls-files --full-name --exclude=*.gemspec --exclude=.*`.chomp.split("\n")
-  
-  if spec_file = Dir['*.gemspec'].first
-    spec = File.read spec_file
-    spec.gsub! /^(\s* s.(test_)?files \s* = \s* )( \[ [^\]]* \] | %w\( [^)]* \) )/mx do
-      assignment = $1
-      bunch = $2 ? list.grep(/^test\//) : list
-      '%s%%w(%s)' % [assignment, bunch.join(' ')]
-    end
-      
-    File.open(spec_file, 'w') { |f| f << 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
-  File.open('.manifest', 'w') { |f| f << list.join("\n") }
-end
 
-task :examples do
-  %x(haml examples/index.haml examples/index.html)
-  %x(sass examples/pagination.sass examples/pagination.css)
+  desc 'Test only ActiveRecord integration'
+  Rake::TestTask.new(:db) do |t|
+    t.pattern = %w[test/finder_test.rb]
+    t.libs << 'test'
+  end
 end

data/lib/will_paginate.rb

@@ -36,12 +36,13 @@ module WillPaginate
 
       # support pagination on associations
       a = ActiveRecord::Associations
-      [ a::AssociationCollection ].tap { |classes|
-        # detect http://dev.rubyonrails.org/changeset/9230
-        unless a::HasManyThroughAssociation.superclass == a::HasManyAssociation
-          classes << a::HasManyThroughAssociation
-        end
-      }.each do |klass|
+      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
@@ -88,3 +89,9 @@ if defined? Rails
   WillPaginate.enable_activerecord if defined? ActiveRecord
   WillPaginate.enable_actionpack if defined? ActionController
 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)
+end

data/lib/will_paginate/array.rb

@@ -1,16 +1,16 @@
 require 'will_paginate/collection'
+require 'will_paginate/per_page'
 
 # 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|
+    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|
       pager.replace self[pager.offset, pager.per_page].to_a
-    }
+    end
   end
 end

data/lib/will_paginate/collection.rb

@@ -1,3 +1,5 @@
+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
@@ -17,8 +19,24 @@ 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
-    def initialize(page, page_num)
-      super "#{page.inspect} given as value, which translates to '#{page_num}' as page number"
+    # 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
     end
   end
   
@@ -44,12 +62,8 @@ 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, 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
-      
+    def initialize(page, per_page = WillPaginate.per_page, total = nil)
+      @current_page, @per_page = InvalidPage.validate(page, per_page)
       self.total_entries = total if total
     end
 

data/lib/will_paginate/finder.rb

@@ -1,4 +1,5 @@
 require 'will_paginate/core_ext'
+require 'will_paginate/per_page'
 
 module WillPaginate
   # A mixin for ActiveRecord::Base. Provides +per_page+ class method
@@ -8,11 +9,10 @@ module WillPaginate
   #
   module Finder
     def self.included(base)
+      base.extend PerPage
       base.extend ClassMethods
       class << base
         alias_method_chain :method_missing, :paginate
-        # alias_method_chain :find_every,     :paginate
-        define_method(:per_page) { 30 } unless respond_to?(:per_page)
       end
     end
 

data/lib/will_paginate/i18n.rb

@@ -0,0 +1,29 @@
+module WillPaginate
+  module I18n
+    def self.locale_dir
+      File.expand_path('../locale', __FILE__)
+    end
+
+    def self.load_path
+      Dir["#{locale_dir}/*.{rb,yml}"]
+    end
+
+    def will_paginate_translate(keys, options = {})
+      if defined? ::I18n
+        defaults = Array(keys).dup
+        if block_given?
+          if defined? ::I18n::Backend::Simple::MATCH
+            # procs in defaults array were not supported back then
+            defaults << yield(defaults.first, options)
+          else
+            defaults << Proc.new
+          end
+        end
+        ::I18n.translate(defaults.shift, options.merge(:default => defaults, :scope => :will_paginate))
+      else
+        key = Array === keys ? keys.first : keys
+        yield key, options
+      end
+    end
+  end
+end

data/lib/will_paginate/locale/en.yml

@@ -0,0 +1,33 @@
+en:
+  will_paginate:
+    previous_label: "« Previous"
+    next_label: "Next »"
+    page_gap: "…"
+
+    page_entries_info:
+      single_page:
+        zero:  "No %{model} found"
+        one:   "Displaying 1 %{model}"
+        other: "Displaying all %{count} %{model}"
+      single_page_html:
+        zero:  "No %{model} found"
+        one:   "Displaying <b>1</b> %{model}"
+        other: "Displaying <b>all&nbsp;%{count}</b> %{model}"
+
+      multi_page: "Displaying %{model} %{from} - %{to} of %{count} in total"
+      multi_page_html: "Displaying %{model} <b>%{from}&nbsp;-&nbsp;%{to}</b> of <b>%{count}</b> in total"
+
+    # models:
+    #   entry:
+    #     zero:  entries
+    #     one:   entry
+    #     few:   entries
+    #     other: entries
+
+    # line_item:
+    #   page_entries_info:
+    #     single_page:
+    #       zero:  "Your shopping cart is empty"
+    #       one:   "Displaying one item in your cart"
+    #       other: "Displaying all %{count} items"
+    #     multi_page: "Displaying items %{from} - %{to} of %{count} in total"

data/lib/will_paginate/per_page.rb

@@ -0,0 +1,27 @@
+module WillPaginate
+  module PerPage
+    def per_page
+      defined?(@per_page) ? @per_page : WillPaginate.per_page
+    end
+
+    def per_page=(limit)
+      @per_page = limit.to_i
+    end
+
+    def self.extended(base)
+      base.extend Inheritance if base.is_a? Class
+    end
+
+    module Inheritance
+      def inherited(subclass)
+        super
+        subclass.per_page = self.per_page
+      end
+    end
+  end
+
+  extend PerPage
+
+  # default number of items per page
+  self.per_page = 30
+end

data/lib/will_paginate/version.rb

@@ -2,7 +2,7 @@ module WillPaginate
   module VERSION
     MAJOR = 2
     MINOR = 3
-    TINY  = 15
+    TINY  = 16
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/will_paginate/view_helpers.rb

@@ -1,4 +1,5 @@
 require 'will_paginate/core_ext'
+require 'will_paginate/i18n'
 
 module WillPaginate
   # = Will Paginate view helpers
@@ -20,11 +21,13 @@ module WillPaginate
   # older versions of Rails) you can easily translate link texts to previous
   # and next pages, as well as override some other defaults to your liking.
   module ViewHelpers
+    include WillPaginate::I18n
+
     # default options that can be overridden on the global level
     @@pagination_options = {
       :class          => 'pagination',
-      :previous_label => '« Previous',
-      :next_label     => 'Next »',
+      :previous_label => nil,
+      :next_label     => nil,
       :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
@@ -102,7 +105,10 @@ module WillPaginate
         WillPaginate::Deprecation::warn(":prev_label view parameter is now :previous_label; the old name has been deprecated", caller)
         options[:previous_label] = options.delete(:prev_label)
       end
-      
+
+      options[:previous_label] ||= will_paginate_translate(:previous_label) { '« Previous' }
+      options[:next_label]     ||= will_paginate_translate(:next_label) { 'Next »' }
+
       # get the renderer instance
       renderer = case options[:renderer]
       when String
@@ -142,7 +148,7 @@ module WillPaginate
     def paginated_section(*args, &block)
       pagination = will_paginate(*args).to_s
       
-      unless ActionView::Base.respond_to? :erb_variable
+      if respond_to? :output_buffer
         concat pagination
         yield
         concat pagination
@@ -160,31 +166,64 @@ module WillPaginate
     #
     # By default, the message will use the humanized class name of objects
     # in collection: for instance, "project types" for ProjectType models.
-    # Override this with the <tt>:entry_name</tt> parameter:
+    # Override this with the <tt>:model</tt> parameter:
     #
-    #   <%= page_entries_info @posts, :entry_name => 'item' %>
+    #   <%= page_entries_info @posts, :model => 'item' %>
     #   #-> Displaying items 6 - 10 of 26 in total
     def page_entries_info(collection, options = {})
-      entry_name = options[:entry_name] ||
-        (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' '))
-      
-      if collection.total_pages < 2
-        case collection.size
-        when 0; "No #{entry_name.pluralize} found"
-        when 1; "Displaying <b>1</b> #{entry_name}"
-        else;   "Displaying <b>all #{collection.size}</b> #{entry_name.pluralize}"
+      if options.key? :entry_name
+        WillPaginate::Deprecation::warn(":entry_name parameter is now called :model", caller)
+      end
+      model = options[:model] || options[:entry_name]
+      model = collection.first.class unless model or collection.empty?
+      model ||= 'entry'
+
+      if html = options.fetch(:html, true)
+        b, eb = '<b>', '</b>'
+        sp = '&nbsp;'
+        html_key = '_html'
+      else
+        b = eb = html_key = ''
+        sp = ' '
+      end
+
+      model_key = model.to_s.underscore
+      model_count = collection.total_pages > 1 ? 5 : collection.size
+      model_name = will_paginate_translate "models.#{model_key}", :count => model_count do |_, opts|
+        name = model_key.to_s.tr('_/', ' ')
+        raise "can't pluralize model name: #{model.inspect}" unless name.respond_to? :pluralize
+        opts[:count] == 1 ? name : name.pluralize
+      end
+
+      output = if collection.total_pages < 2
+        i18n_key = :"page_entries_info.single_page#{html_key}"
+        keys = [:"#{model_key}.#{i18n_key}", i18n_key]
+
+        will_paginate_translate keys, :count => collection.size, :model => model_name do |_, opts|
+          case opts[:count]
+          when 0; "No #{opts[:model]} found"
+          when 1; "Displaying #{b}1#{eb} #{opts[:model]}"
+          else    "Displaying #{b}all#{sp}#{opts[:count]}#{eb} #{opts[:model]}"
+          end
         end
       else
-        %{Displaying #{entry_name.pluralize} <b>%d&nbsp;-&nbsp;%d</b> of <b>%d</b> in total} % [
-          collection.offset + 1,
-          collection.offset + collection.length,
-          collection.total_entries
-        ]
+        i18n_key = :"page_entries_info.multi_page#{html_key}"
+        keys = [:"#{model_key}.#{i18n_key}", i18n_key]
+        params = {
+          :model => model_name, :count => collection.total_entries,
+          :from => collection.offset + 1, :to => collection.offset + collection.length
+        }
+        will_paginate_translate keys, params do |_, opts|
+          %{Displaying %s #{b}%d#{sp}-#{sp}%d#{eb} of #{b}%d#{eb} in total} %
+            [ opts[:model], opts[:from], opts[:to], opts[:count] ]
+        end
+      end
+
+      if html and output.respond_to?(:html_safe)
+        output.html_safe
+      else
+        output
       end
-    end
-    
-    if respond_to? :safe_helper
-      safe_helper :will_paginate, :paginated_section, :page_entries_info
     end
     
     def self.total_pages_for_collection(collection) #:nodoc:
@@ -205,15 +244,6 @@ module WillPaginate
   # This class does the heavy lifting of actually building the pagination
   # links. It is used by the <tt>will_paginate</tt> helper internally.
   class LinkRenderer
-
-    # The gap in page links is represented by:
-    #
-    #   <span class="gap">&hellip;</span>
-    attr_accessor :gap_marker
-    
-    def initialize
-      @gap_marker = '<span class="gap">&hellip;</span>'
-    end
     
     # * +collection+ is a WillPaginate::Collection instance or any other object
     #   that conforms to that API
@@ -253,6 +283,18 @@ module WillPaginate
       end
       @html_attributes
     end
+
+    attr_writer :gap_marker
+
+    # The gap in page links is represented by:
+    #
+    #   <span class="gap">&hellip;</span>
+    def gap_marker
+      @gap_marker ||= begin
+        gap_text = @template.will_paginate_translate(:page_gap) { '&hellip;' }
+        %(<span class="gap">#{gap_text}</span>)
+      end
+    end
     
   protected
 
@@ -395,7 +437,8 @@ module WillPaginate
       if defined? Rack::Utils
         # For Rails > 2.3
         Rack::Utils.parse_nested_query(params)
-      elsif defined?(ActionController::AbstractRequest)
+      elsif defined?(ActionController::AbstractRequest) and
+          ActionController::AbstractRequest.respond_to? :parse_query_parameters
         ActionController::AbstractRequest.parse_query_parameters(params)
       elsif defined?(ActionController::UrlEncodedPairParser)
         # For Rails > 2.2