mislav-will_paginate 2.3.2 → 2.3.3

data/{CHANGELOG → CHANGELOG.rdoc}

@@ -1,3 +1,10 @@
+== 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://mislav.caboo.se/static/will_paginate/doc/)
+* 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

data/README.rdoc

@@ -11,32 +11,11 @@ can.
 
 Some resources to get you started:
 
+* {Installation instructions}[http://github.com/mislav/will_paginate/wikis/installation]
+  on {the wiki}[http://github.com/mislav/will_paginate/wikis]
 * Your mind reels with questions? Join our
   {Google group}[http://groups.google.com/group/will_paginate].
-* The will_paginate project page: http://github.com/mislav/will_paginate
-* How to report bugs: http://github.com/mislav/will_paginate/wikis/report-bugs
-* Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51],
-  check it out.
-
-== Installation
-
-The recommended way is that you get the gem:
-
-  gem install mislav-will_paginate --source http://gems.github.com/
-
-After that you don't need the will_paginate <i>plugin</i> in your Rails
-application anymore. Just add a simple require to the end of
-"config/environment.rb":
-
-  gem 'mislav-will_paginate', '~> 2.2'
-  require 'will_paginate'
-
-That's it. Remember to install the gem on <b>all</b> 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>
+* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs]
 
 
 == Example usage
@@ -54,8 +33,7 @@ pagination, just stick this in:
 
   <%= will_paginate @posts %>
 
-You're done. (Copy and paste the example fancy CSS styles from the bottom.) You
-can find the option list at WillPaginate::ViewHelpers.
+You're done. (You can find the option list at WillPaginate::ViewHelpers.)
 
 How does it know how much items to fetch per page? It asks your model by calling
 its <tt>per_page</tt> class method. You can define it like this:
@@ -115,16 +93,13 @@ Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris Eppstein.
 == Usable pagination in the UI
 
 There are some CSS styles to get you started in the "examples/" directory. They
-are showcased in the <b>"examples/index.html"</b> file.
+are {showcased online here}[http://mislav.caboo.se/static/will_paginate/].
 
 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/
-* Pagination on Yahoo Design Pattern Library:
-  http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination
+* {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/]
+* {Pagination on Yahoo Design Pattern Library}[http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination]
 
 Want to discuss, request features, ask questions? Join the
 {Google group}[http://groups.google.com/group/will_paginate].

data/Rakefile

@@ -1,6 +1,6 @@
 require 'rubygems'
 begin
-  hanna_dir = '/home/mislav/projects/hanna/lib'
+  hanna_dir = '/Users/mislav/Projects/Hanna/lib'
   $:.unshift hanna_dir if File.exists? hanna_dir
   require 'hanna/rdoctask'
 rescue LoadError
@@ -14,7 +14,7 @@ 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.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG.rdoc').
     include('lib/**/*.rb').
     exclude('lib/will_paginate/named_scope*').
     exclude('lib/will_paginate/array.rb').

data/lib/will_paginate.rb

@@ -9,29 +9,29 @@ require 'active_support'
 # Happy paginating!
 module WillPaginate
   class << self
-    # shortcut for <tt>enable_actionpack; enable_activerecord</tt>
+    # shortcut for <tt>enable_actionpack</tt> and <tt>enable_activerecord</tt> combined
     def enable
       enable_actionpack
       enable_activerecord
     end
     
-    # mixes in WillPaginate::ViewHelpers in ActionView::Base
+    # hooks WillPaginate::ViewHelpers into ActionView::Base
     def enable_actionpack
       return if ActionView::Base.instance_methods.include? 'will_paginate'
       require 'will_paginate/view_helpers'
-      ActionView::Base.class_eval { include ViewHelpers }
+      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
     
-    # mixes in WillPaginate::Finder in ActiveRecord::Base and classes that deal
+    # 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.class_eval { include Finder }
+      ActiveRecord::Base.send :include, Finder
 
       # support pagination on associations
       a = ActiveRecord::Associations
@@ -41,10 +41,8 @@ module WillPaginate
           classes << a::HasManyThroughAssociation
         end
       }.each do |klass|
-        klass.class_eval do
-          include Finder::ClassMethods
-          alias_method_chain :method_missing, :paginate
-        end
+        klass.send :include, Finder::ClassMethods
+        klass.class_eval { alias_method_chain :method_missing, :paginate }
       end
     end
 
@@ -61,13 +59,11 @@ module WillPaginate
       require 'will_paginate/named_scope'
       require 'will_paginate/named_scope_patch' if patch
 
-      ActiveRecord::Base.class_eval do
-        include WillPaginate::NamedScope
-      end
+      ActiveRecord::Base.send :include, WillPaginate::NamedScope
     end
   end
 
-  module Deprecation #:nodoc:
+  module Deprecation # :nodoc:
     extend ActiveSupport::Deprecation
 
     def self.warn(message, callstack = caller)

data/lib/will_paginate/collection.rb

@@ -33,12 +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 the "will_paginate" gem:
+  # make your plugin/gem dependant on the "mislav-will_paginate" gem:
   #
-  #   gem 'will_paginate'
+  #   gem 'mislav-will_paginate'
   #   require 'will_paginate/collection'
   #   
-  #   # now use WillPaginate::Collection directly or subclass it
+  #   # WillPaginate::Collection is now available for use
   class Collection < Array
     attr_reader :current_page, :per_page, :total_entries, :total_pages
 
@@ -98,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
-    # besides your records: simply start with offset + 1.
+    # side by side with records in the view: simply start with offset + 1.
     def offset
       (current_page - 1) * per_page
     end
@@ -112,7 +112,8 @@ 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/finder.rb

@@ -94,8 +94,8 @@ module WillPaginate
       # 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.
+      # See {Faking Cursors in ActiveRecord}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
+      # where Jamis Buck describes this and a more efficient way for MySQL.
       def paginated_each(options = {}, &block)
         options = { :order => 'id', :page => 1 }.merge options
         options[:page] = options[:page].to_i
@@ -127,7 +127,7 @@ module WillPaginate
       # 
       def paginate_by_sql(sql, options)
         WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
-          query = sanitize_sql(sql)
+          query = sanitize_sql(sql.dup)
           original_query = query.dup
           # add limit, offset
           add_limit! query, :offset => pager.offset, :limit => pager.per_page
@@ -184,19 +184,27 @@ module WillPaginate
         unless options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
           excludees << :select # only exclude the select param if it doesn't begin with DISTINCT
         end
+
         # count expects (almost) the same options as find
         count_options = options.except *excludees
 
         # merge the hash found in :count
         # this allows you to specify :select, :order, or anything else just for the count query
         count_options.update options[:count] if options[:count]
+        
+        # we may be in a model or an association proxy
+        klass = (@owner and @reflection) ? @reflection.klass : self
+        
+        # forget about includes if they are irrelevant (Rails 2.1)
+        if count_options[:include] and
+            klass.private_methods.include?('references_eager_loaded_tables?') and
+            !klass.send(:references_eager_loaded_tables?, count_options)
+          count_options.delete :include
+        end
 
         # we may have to scope ...
         counter = Proc.new { count(count_options) }
 
-        # we may be in a model or an association proxy!
-        klass = (@owner and @reflection) ? @reflection.klass : self
-
         count = if finder.index('find_') == 0 and klass.respond_to?(scoper = finder.sub('find', 'with'))
                   # scope_out adds a 'with_finder' method which acts like with_scope, if it's present
                   # then execute the count with the scoping provided by the with_finder

data/lib/will_paginate/version.rb

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

data/lib/will_paginate/view_helpers.rb

@@ -3,35 +3,36 @@ require 'will_paginate/core_ext'
 module WillPaginate
   # = Will Paginate view helpers
   #
-  # Currently there is only one view helper: +will_paginate+. It renders the
+  # The main view helper, #will_paginate, renders
   # pagination links for the given collection. The helper itself is lightweight
-  # and serves only as a wrapper around link renderer instantiation; the
+  # and serves only as a wrapper around LinkRenderer instantiation; the
   # renderer then does all the hard work of generating the HTML.
   # 
   # == 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
+  # <tt>WillPaginate::ViewHelpers.pagination_options</tt> hash. You can write to this hash to
   # override default options on the global level:
   #
-  #   WillPaginate::ViewHelpers.pagination_options[:prev_label] = 'Previous page'
+  #   WillPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous page'
   #
-  # By putting this into your environment.rb you can easily translate link texts to previous
+  # By putting this into "config/initializers/will_paginate.rb" (or simply environment.rb in
+  # 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
     # default options that can be overridden on the global level
     @@pagination_options = {
-      :class        => 'pagination',
-      :prev_label   => '&laquo; Previous',
-      :next_label   => 'Next &raquo;',
-      :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::LinkRenderer',
-      :page_links   => true,
-      :container    => true
+      :class          => 'pagination',
+      :previous_label => '&laquo; Previous',
+      :next_label     => 'Next &raquo;',
+      :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::LinkRenderer',
+      :page_links     => true,
+      :container      => true
     }
     mattr_reader :pagination_options
 
@@ -40,32 +41,37 @@ module WillPaginate
     # rendering the pagination in that case...
     # 
     # ==== Options
-    # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
-    # * <tt>:prev_label</tt> -- default: "« Previous"
+    # Display options:
+    # * <tt>:previous_label</tt> -- default: "« Previous" (this parameter is called <tt>:prev_label</tt> in versions <b>2.3.2</b> and older!)
     # * <tt>:next_label</tt> -- default: "Next »"
+    # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
     # * <tt>:inner_window</tt> -- how many links are shown around the current page (default: 4)
     # * <tt>:outer_window</tt> -- how many links are around the first and the last page (default: 1)
     # * <tt>:separator</tt> -- string separator for page HTML elements (default: single space)
-    # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
-    # * <tt>:params</tt> -- additional parameters when generating pagination links
-    #   (eg. <tt>:controller => "foo", :action => nil</tt>)
-    # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
-    #   <tt>WillPaginate::LinkRenderer</tt>)
-    # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
+    # 
+    # HTML options:
+    # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
     # * <tt>:container</tt> -- toggles rendering of the DIV container for pagination links, set to
     #   false only when you are rendering your own pagination markup (default: true)
     # * <tt>:id</tt> -- HTML ID for the container (default: nil). Pass +true+ to have the ID
     #   automatically generated from the class name of objects in collection: for example, paginating
     #   ArticleComment models would yield an ID of "article_comments_pagination".
     #
-    # All options beside listed ones are passed as HTML attributes to the container
+    # Advanced options:
+    # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
+    # * <tt>:params</tt> -- additional parameters when generating pagination links
+    #   (eg. <tt>:controller => "foo", :action => nil</tt>)
+    # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
+    #   <tt>WillPaginate::LinkRenderer</tt>)
+    #
+    # All options not recognized by will_paginate will become HTML attributes on the container
     # element for pagination links (the DIV). For example:
     # 
-    #   <%= will_paginate @posts, :id => 'wp_posts' %>
+    #   <%= will_paginate @posts, :style => 'font-size: small' %>
     #
     # ... will result in:
     #
-    #   <div class="pagination" id="wp_posts"> ... </div>
+    #   <div class="pagination" style="font-size: small"> ... </div>
     #
     # ==== Using the helper without arguments
     # If the helper is called without passing in the collection object, it will
@@ -92,6 +98,10 @@ module WillPaginate
       return nil unless WillPaginate::ViewHelpers.total_pages_for_collection(collection) > 1
       
       options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options
+      if options[:prev_label]
+        WillPaginate::Deprecation::warn(":prev_label view parameter is now :previous_label; the old name has been deprecated.")
+        options[:previous_label] = options.delete(:prev_label)
+      end
       
       # get the renderer instance
       renderer = case options[:renderer]
@@ -143,7 +153,7 @@ 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 to your liking with the <tt>:entry_name</tt> parameter:
+    # Override this with the <tt>:entry_name</tt> parameter:
     #
     #   <%= page_entries_info @posts, :entry_name => 'item' %>
     #   #-> Displaying items 6 - 10 of 26 in total
@@ -183,7 +193,7 @@ module WillPaginate
   end
 
   # This class does the heavy lifting of actually building the pagination
-  # links. It is used by +will_paginate+ helper internally.
+  # links. It is used by the <tt>will_paginate</tt> helper internally.
   class LinkRenderer
 
     # The gap in page links is represented by:
@@ -214,7 +224,7 @@ module WillPaginate
     def to_html
       links = @options[:page_links] ? windowed_links : []
       # previous/next buttons
-      links.unshift page_link_or_span(@collection.previous_page, 'disabled prev_page', @options[:prev_label])
+      links.unshift page_link_or_span(@collection.previous_page, 'disabled prev_page', @options[:previous_label])
       links.push    page_link_or_span(@collection.next_page,     'disabled next_page', @options[:next_label])
       
       html = links.join(@options[:separator])

data/test/database.yml

@@ -9,8 +9,8 @@ sqlite2:
 
 mysql:
   adapter: mysql
-  username: rails
-  password: mislav
+  username: root
+  password: 
   encoding: utf8
   database: will_paginate_unittest
 

data/test/finder_test.rb

@@ -397,6 +397,15 @@ class FinderTest < ActiveRecordTestCase
       Developer.paginate(options)
       assert_equal options, options_before
     end
+    
+    def test_paginate_by_sql_doesnt_change_original_query
+      query = 'SQL QUERY'
+      original_query = query.dup
+      Developer.expects(:find_by_sql).returns([])
+      
+      Developer.paginate_by_sql query, :page => 1
+      assert_equal original_query, query
+    end
 
     def test_paginated_each
       collection = stub('collection', :size => 5, :empty? => false, :per_page => 5)
@@ -412,5 +421,23 @@ class FinderTest < ActiveRecordTestCase
       
       assert_equal 14, Developer.paginated_each(:page => '2') { }
     end
+
+    # detect ActiveRecord 2.1
+    if ActiveRecord::Base.private_methods.include?('references_eager_loaded_tables?')
+      def test_removes_irrelevant_includes_in_count
+        Developer.expects(:find).returns([1])
+        Developer.expects(:count).with({}).returns(0)
+
+        Developer.paginate :page => 1, :per_page => 1, :include => :projects
+      end
+
+      def test_doesnt_remove_referenced_includes_in_count
+        Developer.expects(:find).returns([1])
+        Developer.expects(:count).with({ :include => :projects, :conditions => 'projects.id > 2' }).returns(0)
+
+        Developer.paginate :page => 1, :per_page => 1,
+          :include => :projects, :conditions => 'projects.id > 2'
+      end
+    end
   end
 end

data/test/tasks.rake

@@ -32,18 +32,21 @@ task :test_databases => %w(test_mysql test_sqlite3 test_postgres)
 desc %{Test everything on SQLite3, MySQL and PostgreSQL}
 task :test_full => %w(test test_mysql test_postgres)
 
-desc %{Test everything with Rails 1.2.x and 2.0.x gems}
+desc %{Test everything with Rails 2.1.x, 2.0.x & 1.2.x gems}
 task :test_all do
   all = Rake::Task['test_full']
-  ENV['RAILS_VERSION'] = '~>1.2.6'
-  all.invoke 
-  # reset the invoked flag
+  versions = %w(2.1.0 2.0.2 1.2.6)
+  versions.each do |version|
+    ENV['RAILS_VERSION'] = "~> #{version}"
+    all.invoke
+    reset_invoked unless version == versions.last
+  end
+end
+
+def reset_invoked
   %w( test_full test test_mysql test_postgres ).each do |name|
     Rake::Task[name].instance_variable_set '@already_invoked', false
   end
-  # do it again
-  ENV['RAILS_VERSION'] = '~>2.0.2'
-  all.invoke 
 end
 
 task :rcov do

data/test/view_test.rb

@@ -36,7 +36,7 @@ class ViewTest < WillPaginate::ViewTestCase
 
   def test_will_paginate_with_options
     paginate({ :page => 2 },
-             :class => 'will_paginate', :prev_label => 'Prev', :next_label => 'Next') do
+             :class => 'will_paginate', :previous_label => 'Prev', :next_label => 'Next') do
       assert_select 'a[href]', 4 do |elements|
         validate_page_numbers [1,1,3,3], elements
         # test rel attribute values:
@@ -80,6 +80,14 @@ class ViewTest < WillPaginate::ViewTestCase
       assert_select 'a.next_page[href]:last-child'
     end
   end
+  
+  def test_prev_label_deprecated
+    assert_deprecated ':previous_label' do
+      paginate({ :page => 2 }, :prev_label => 'Deprecated') do
+        assert_select 'a[href]:first-child', 'Deprecated'
+      end
+    end
+  end
 
   def test_full_output
     paginate

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mislav-will_paginate
 version: !ruby/object:Gem::Version 
-  version: 2.3.2
+  version: 2.3.3
 platform: ruby
 authors: 
 - "Mislav Marohni\xC4\x87"
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-05-16 00:00:00 -07:00
+date: 2008-08-29 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,9 +31,9 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 - LICENSE
-- CHANGELOG
+- CHANGELOG.rdoc
 files: 
-- CHANGELOG
+- CHANGELOG.rdoc
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.0.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: Most awesome pagination solution for Rails