Will Paginate: add support for custom renderers. Polish the API for W…

…P::LinkRenderer a bit. README tweaks. Link to page 1 finally gets the "page=1" parameter, there was too much trouble in various cases when it was ommited. [mislav#157 state:resolved]

git-svn-id: svn://errtheblog.com/svn/plugins/will_paginate@423 1eaa51fe-a21a-0410-9c2e-ae7a00a434c4

README

@@ -1,21 +1,25 @@
 = WillPaginate
 
 Pagination is just limiting the number of records displayed. Why should you let
-it get in your way while doing more important tasks on your project? This
-plugin makes magic happen. Ever wanted to be able to do just this:
+it get in your way while developing, then? This plugin makes magic happen. Did
+you ever want to be able to do just this on a model:
 
   Post.paginate :page => 1
 
-... and then render the page links with a single call to a view helper? Well,
-now you can. Simply:
+... and then render the page links with a single view helper? Well, now you
+can. Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51],
+check it out.
 
-  script/plugin install svn://errtheblog.com/svn/plugins/will_paginate
+Need to ask questions? Join our Google
+group[http://groups.google.com/group/will_paginate].
+
+== Install the plugin
 
-Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51], check
-it out.
+Simply do:
 
+  script/plugin install svn://errtheblog.com/svn/plugins/will_paginate
 
-== Example usage:
+== Example usage
 
 Use a paginate finder in the controller:
 
@@ -77,7 +81,7 @@ BROWSE SOURCE on Warehouse: http://plugins.require.errtheblog.com/browser/will_p
 Want to discuss, request features, ask questions? Join the Google group:
 http://groups.google.com/group/will_paginate
 
-  Ruby port by:           PJ Hyett, Mislav Marohnić (Sulien)
+  Authors:                Mislav Marohnić, PJ Hyett
   Original announcement:  http://errtheblog.com/post/929 
   Original PHP source:    http://www.strangerstudios.com/sandbox/pagination/diggstyle.php
   Contributors:           Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, 

lib/will_paginate/view_helpers.rb

@@ -20,7 +20,8 @@ module ViewHelpers
           :outer_window => 1, # links around beginning and end
           :separator    => ' ', # single space is friendly to spiders and non-graphic browsers
           :param_name   => :page,
-          :params       => nil
+          :params       => nil,
+          :renderer     => 'WillPaginate::LinkRenderer'
           }
     mattr_reader :pagination_options
 
@@ -38,6 +39,7 @@ module ViewHelpers
     #   param_name:   parameter name for page number in URLs, defaults to "page"
     #   params:       additional parameters when generating pagination links
     #                 (eg. :controller => 'foo', :action => nil)
+    #   renderer:     class name of the link renderer, defaults to WillPaginate::LinkRenderer
     #
     # All options beside listed ones are passed as HTML attributes to the container
     # element for pagination links (the DIV). For example:
@@ -48,13 +50,16 @@ module ViewHelpers
     #
     #   <div class="pagination" id="wp_posts"> ... </div>
     #
-    def will_paginate(entries = @entries, options = {})
-      if entries.page_count > 1
-        renderer = WillPaginate::LinkRenderer.new entries, options, self
-        links = renderer.items
-
-        content_tag :div, links, renderer.html_options
-      end
+    def will_paginate(collection = nil, options = {})
+      collection = instance_variable_get("@#{controller.controller_name}") unless collection
+      # early exit if there is nothing to render
+      return nil unless collection.page_count > 1
+      options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options
+      # create the renderer instance
+      renderer_class = options[:renderer].to_s.constantize
+      renderer = renderer_class.new collection, options, self
+      # render HTML for pagination
+      content_tag :div, renderer.to_html, renderer.html_attributes
     end
   end
 
@@ -65,20 +70,20 @@ class LinkRenderer
 
     def initialize(collection, options, template)
       @collection = collection
-      @options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options
-      @template = template
+      @options    = options
+      @template   = template
     end
 
-    def items
+    def to_html
       returning windowed_paginator do |links|
         # next and previous buttons
         links.unshift page_link_or_span(@collection.previous_page, 'disabled', @options[:prev_label])
         links.push    page_link_or_span(@collection.next_page,     'disabled', @options[:next_label])
       end.join(@options[:separator])
     end
 
-    def html_options
-      @options.except *(WillPaginate::ViewHelpers.pagination_options.keys - [:class])
+    def html_attributes
+      @html_attributes ||= @options.except *(WillPaginate::ViewHelpers.pagination_options.keys - [:class])
     end
 
   protected
@@ -126,7 +131,7 @@ def page_link_or_span(page, span_class, text)
     end
 
     def url_options(page)
-      options = { param_name => page != 1 ? page : nil }
+      options = { param_name => page }
       # page links should preserve GET parameters
       options = params.merge(options) if @template.request.get?
       options.rec_merge!(@options[:params]) if @options[:params]

test/pagination_test.rb

@@ -14,7 +14,7 @@
 
 class PaginationTest < Test::Unit::TestCase
 
-  class PaginationController < ActionController::Base
+  class DevelopersController < ActionController::Base
     def list_developers
       @options = session[:wp] || {}
 
@@ -26,13 +26,18 @@ def list_developers
       render :inline => '<%= will_paginate @developers, @options %>'
     end
 
+    def guess_collection_name
+      @developers = session[:wp]
+      render :inline => '<%= will_paginate %>'
+    end
+
     protected
       def rescue_errors(e) raise e end
       def rescue_action(e) raise e end
   end
 
   def setup
-    @controller = PaginationController.new
+    @controller = DevelopersController.new
     @request    = ActionController::TestRequest.new
     @response   = ActionController::TestResponse.new
     super
@@ -68,7 +73,7 @@ def test_will_paginate_with_options
 
     assert_select 'div.will_paginate', 1, 'no main DIV' do
       assert_select 'a[href]', 4 do |elements|
-        validate_page_numbers [nil,nil,3,3], elements
+        validate_page_numbers [1,1,3,3], elements
         assert_select elements.first, 'a', "Prev"
         assert_select elements.last, 'a', "Next"
       end
@@ -111,7 +116,7 @@ def test_will_paginate_with_custom_page_param
 
     assert_select 'div.pagination', 1, 'no main DIV' do
       assert_select 'a[href]', 4 do |elements|
-        validate_page_numbers [nil,nil,3,3], elements, :developers_page
+        validate_page_numbers [1,1,3,3], elements, :developers_page
       end
       assert_select 'span.current', entries.current_page.to_s
     end    
@@ -127,7 +132,7 @@ def test_will_paginate_windows
 
     assert_select 'div.pagination', 1, 'no main DIV' do
       assert_select 'a[href]', 10 do |elements|
-        validate_page_numbers [5,nil,2,4,5,7,8,10,11,7], elements
+        validate_page_numbers [5,1,2,4,5,7,8,10,11,7], elements
         assert_select elements.first, 'a', "&laquo; Previous"
         assert_select elements.last, 'a', "Next &raquo;"
       end
@@ -144,11 +149,19 @@ def test_no_pagination
     assert_equal '', @response.body
   end
 
-  def test_faulty_input
+  def test_faulty_input_raises_error
     assert_raise WillPaginate::InvalidPage do
       get :list_developers, :page => 'foo'
     end
   end
+
+  uses_mocha 'helper internals' do
+    def test_collection_name_can_be_guessed
+      collection = mock
+      collection.expects(:page_count).returns(1)
+      get :guess_collection_name, {}, :wp => collection
+    end
+  end
 
 protected