auxesis-will_paginate 3.0.0

data/lib/will_paginate/view_helpers/base.rb

@@ -0,0 +1,126 @@
+require 'will_paginate/core_ext'
+require 'will_paginate/view_helpers'
+
+module WillPaginate
+  module ViewHelpers
+    # = The main view helpers module
+    #
+    # This is the base module which provides the +will_paginate+ view helper.
+    module Base
+      # Renders Digg/Flickr-style pagination for a WillPaginate::Collection object. Nil is
+      # returned if there is only one page in total; pagination links aren't needed in that case.
+      # 
+      # ==== Options
+      # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
+      # * <tt>:previous_label</tt> -- default: "« Previous"
+      # * <tt>:next_label</tt> -- default: "Next »"
+      # * <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)
+      # * <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
+      # element for pagination links (the DIV). For example:
+      # 
+      #   <%= will_paginate @posts, :id => 'wp_posts' %>
+      #
+      # ... will result in:
+      #
+      #   <div class="pagination" id="wp_posts"> ... </div>
+      #
+      def will_paginate(collection, options = {})
+        # early exit if there is nothing to render
+        return nil unless collection.total_pages > 1
+        
+        options = WillPaginate::ViewHelpers.pagination_options.merge(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]
+        when String
+          options[:renderer].constantize.new
+        when Class
+          options[:renderer].new
+        else
+          options[:renderer]
+        end
+        # render HTML for pagination
+        renderer.prepare collection, options, self
+        renderer.to_html
+      end
+      
+      # Renders a helpful message with numbers of displayed vs. total entries.
+      # You can use this as a blueprint for your own, similar helpers.
+      #
+      #   <%= page_entries_info @posts %>
+      #   #-> Displaying posts 6 - 10 of 26 in total
+      #
+      # 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:
+      #
+      #   <%= page_entries_info @posts, :entry_name => 'item' %>
+      #   #-> Displaying items 6 - 10 of 26 in total
+      #
+      # Entry name is entered in singular and pluralized with
+      # <tt>String#pluralize</tt> method from ActiveSupport. If it isn't
+      # loaded, specify plural with <tt>:plural_name</tt> parameter:
+      #
+      #   <%= page_entries_info @posts, :entry_name => 'item', :plural_name => 'items' %>
+      #
+      # By default, this method produces HTML output. You can trigger plain
+      # text output by passing <tt>:html => false</tt> in options.
+      def page_entries_info(collection, options = {})
+        entry_name = options[:entry_name] || (collection.empty?? 'entry' :
+                     collection.first.class.name.underscore.gsub('_', ' '))
+        
+        plural_name = if options[:plural_name]
+          options[:plural_name]
+        elsif entry_name == 'entry'
+          plural_name = 'entries'
+        elsif entry_name.respond_to? :pluralize
+          plural_name = entry_name.pluralize
+        else
+          entry_name + 's'
+        end
+
+        unless options[:html] == false
+          b  = '<b>'
+          eb = '</b>'
+          sp = '&nbsp;'
+        else
+          b  = eb = ''
+          sp = ' '
+        end
+        
+        if collection.total_pages < 2
+          case collection.size
+          when 0; "No #{plural_name} found"
+          when 1; "Displaying #{b}1#{eb} #{entry_name}"
+          else;   "Displaying #{b}all #{collection.size}#{eb} #{plural_name}"
+          end
+        else
+          %{Displaying #{plural_name} #{b}%d#{sp}-#{sp}%d#{eb} of #{b}%d#{eb} in total} % [
+            collection.offset + 1,
+            collection.offset + collection.length,
+            collection.total_entries
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/will_paginate/view_helpers/link_renderer.rb

@@ -0,0 +1,130 @@
+require 'cgi'
+require 'will_paginate/core_ext'
+require 'will_paginate/view_helpers/link_renderer_base'
+
+module WillPaginate
+  module ViewHelpers
+    # This class does the heavy lifting of actually building the pagination
+    # links. It is used by +will_paginate+ helper internally.
+    class LinkRenderer < LinkRendererBase
+      
+      # * +collection+ is a WillPaginate::Collection instance or any other object
+      #   that conforms to that API
+      # * +options+ are forwarded from +will_paginate+ view helper
+      # * +template+ is the reference to the template being rendered
+      def prepare(collection, options, template)
+        super(collection, options)
+        @template = template
+        @container_attributes = @base_url_params = nil
+      end
+
+      # Process it! This method returns the complete HTML string which contains
+      # pagination links. Feel free to subclass LinkRenderer and change this
+      # method as you see fit.
+      def to_html
+        html = pagination.map do |item|
+          item.is_a?(Fixnum) ?
+            page_number(item) :
+            send(item)
+        end.join(@options[:separator])
+        
+        @options[:container] ? html_container(html) : html
+      end
+
+      # Returns the subset of +options+ this instance was initialized with that
+      # represent HTML attributes for the container element of pagination links.
+      def container_attributes
+        @container_attributes ||= begin
+          attributes = @options.except *(WillPaginate::ViewHelpers.pagination_options.keys - [:class])
+          # pagination of Post models will have the ID of "posts_pagination"
+          if @options[:container] and @options[:id] === true
+            attributes[:id] = @collection.first.class.name.underscore.pluralize + '_pagination'
+          end
+          attributes
+        end
+      end
+      
+    protected
+    
+      def page_number(page)
+        unless page == current_page
+          link(page, page, :rel => rel_value(page))
+        else
+          tag(:em, page)
+        end
+      end
+      
+      def gap
+        '<span class="gap">&hellip;</span>'
+      end
+      
+      def previous_page
+        previous_or_next_page(@collection.previous_page, @options[:previous_label], 'previous_page')
+      end
+      
+      def next_page
+        previous_or_next_page(@collection.next_page, @options[:next_label], 'next_page')
+      end
+      
+      def previous_or_next_page(page, text, classname)
+        if page
+          link(text, page, :class => classname)
+        else
+          tag(:span, text, :class => classname + ' disabled')
+        end
+      end
+      
+      def html_container(html)
+        tag(:div, html, container_attributes)
+      end
+      
+      # Returns URL params for +page_link_or_span+, taking the current GET params
+      # and <tt>:params</tt> option into account.
+      def url(page)
+        raise NotImplementedError
+      end
+      
+    private
+
+      def link(text, target, attributes = {})
+        if target.is_a? Fixnum
+          attributes[:rel] = rel_value(target)
+          target = url(target)
+        end
+        attributes[:href] = target
+        tag(:a, text, attributes)
+      end
+      
+      def tag(name, value, attributes = {})
+        string_attributes = attributes.inject('') do |attrs, pair|
+          unless pair.last.nil?
+            attrs << %( #{pair.first}="#{CGI::escapeHTML(pair.last.to_s)}")
+          end
+          attrs
+        end
+        "<#{name}#{string_attributes}>#{value}</#{name}>"
+      end
+
+      def rel_value(page)
+        case page
+        when @collection.previous_page; 'prev' + (page == 1 ? ' start' : '')
+        when @collection.next_page; 'next'
+        when 1; 'start'
+        end
+      end
+
+      def symbolized_update(target, other)
+        other.each do |key, value|
+          key = key.to_sym
+          existing = target[key]
+          
+          if value.is_a?(Hash) and (existing.is_a?(Hash) or existing.nil?)
+            symbolized_update(existing || (target[key] = {}), value)
+          else
+            target[key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/will_paginate/view_helpers/link_renderer_base.rb

@@ -0,0 +1,83 @@
+require 'will_paginate/view_helpers'
+
+module WillPaginate
+  module ViewHelpers
+    # This class does the heavy lifting of actually building the pagination
+    # links. It is used by +will_paginate+ helper internally.
+    class LinkRendererBase
+
+      # * +collection+ is a WillPaginate::Collection instance or any other object
+      #   that conforms to that API
+      # * +options+ are forwarded from +will_paginate+ view helper
+      def prepare(collection, options)
+        @collection = collection
+        @options    = options
+
+        # reset values in case we're re-using this instance
+        @total_pages = @param_name = nil
+      end
+      
+      def pagination
+        items = @options[:page_links] ? windowed_page_numbers : []
+        items.unshift :previous_page
+        items.push :next_page
+      end
+
+    protected
+    
+      # Calculates visible page numbers using the <tt>:inner_window</tt> and
+      # <tt>:outer_window</tt> options.
+      def windowed_page_numbers
+        inner_window, outer_window = @options[:inner_window].to_i, @options[:outer_window].to_i
+        window_from = current_page - inner_window
+        window_to = current_page + inner_window
+        
+        # adjust lower or upper limit if other is out of bounds
+        if window_to > total_pages
+          window_from -= window_to - total_pages
+          window_to = total_pages
+        end
+        if window_from < 1
+          window_to += 1 - window_from
+          window_from = 1
+          window_to = total_pages if window_to > total_pages
+        end
+        
+        # these are always visible
+        middle = window_from..window_to
+
+        # left window
+        if outer_window + 3 < middle.first # there's a gap
+          left = (1..(outer_window + 1)).to_a
+          left << :gap
+        else # runs into visible pages
+          left = 1...middle.first
+        end
+
+        # right window
+        if total_pages - outer_window - 2 > middle.last # again, gap
+          right = ((total_pages - outer_window)..total_pages).to_a
+          right.unshift :gap
+        else # runs into visible pages
+          right = (middle.last + 1)..total_pages
+        end
+        
+        left.to_a + middle.to_a + right.to_a
+      end
+
+    private
+
+      def current_page
+        @collection.current_page
+      end
+
+      def total_pages
+        @collection.total_pages
+      end
+
+      def param_name
+        @param_name ||= @options[:param_name].to_s
+      end
+    end
+  end
+end

data/lib/will_paginate/view_helpers/merb.rb

@@ -0,0 +1,13 @@
+require 'will_paginate/view_helpers/base'
+require 'will_paginate/view_helpers/link_renderer'
+
+WillPaginate::ViewHelpers::LinkRenderer.class_eval do
+  protected
+
+  def url(page)
+    params = @template.request.params.except(:action, :controller).merge('page' => page)
+    @template.url(:this, params)
+  end
+end
+
+Merb::AbstractController.send(:include, WillPaginate::ViewHelpers::Base)

data/spec/collection_spec.rb

@@ -0,0 +1,147 @@
+require 'will_paginate/array'
+require 'spec_helper'
+
+describe WillPaginate::Collection do
+
+  before :all do
+    @simple = ('a'..'e').to_a
+  end
+
+  it "should be a subset of original collection" do
+    @simple.paginate(:page => 1, :per_page => 3).should == %w( a b c )
+  end
+
+  it "can be shorter than per_page if on last page" do
+    @simple.paginate(:page => 2, :per_page => 3).should == %w( d e )
+  end
+
+  it "should include whole collection if per_page permits" do
+    @simple.paginate(:page => 1, :per_page => 5).should == @simple
+  end
+
+  it "should be empty if out of bounds" do
+    @simple.paginate(:page => 2, :per_page => 5).should be_empty
+  end
+  
+  it "should default to 1 as current page and 30 per-page" do
+    result = (1..50).to_a.paginate
+    result.current_page.should == 1
+    result.size.should == 30
+  end
+
+  describe "old API" do
+    it "should fail with numeric params" do
+      Proc.new { [].paginate(2) }.should raise_error(ArgumentError)
+      Proc.new { [].paginate(2, 10) }.should raise_error(ArgumentError)
+    end
+
+    it "should fail with both options and numeric param" do
+      Proc.new { [].paginate({}, 5) }.should raise_error(ArgumentError)
+    end
+  end
+
+  it "should give total_entries precedence over actual size" do
+    %w(a b c).paginate(:total_entries => 5).total_entries.should == 5
+  end
+
+  it "should be an augmented Array" do
+    entries = %w(a b c)
+    collection = create(2, 3, 10) do |pager|
+      pager.replace(entries).should == entries
+    end
+
+    collection.should == entries
+    for method in %w(total_pages each offset size current_page per_page total_entries)
+      collection.should respond_to(method)
+    end
+    collection.should be_kind_of(Array)
+    collection.entries.should be_instance_of(Array)
+    # TODO: move to another expectation:
+    collection.offset.should == 3
+    collection.total_pages.should == 4
+    collection.should_not be_out_of_bounds
+  end
+
+  describe "previous/next pages" do
+    it "should have previous_page nil when on first page" do
+      collection = create(1, 1, 3)
+      collection.previous_page.should be_nil
+      collection.next_page.should == 2
+    end
+    
+    it "should have both prev/next pages" do
+      collection = create(2, 1, 3)
+      collection.previous_page.should == 1
+      collection.next_page.should == 3
+    end
+    
+    it "should have next_page nil when on last page" do
+      collection = create(3, 1, 3)
+      collection.previous_page.should == 2
+      collection.next_page.should be_nil
+    end
+  end
+
+  it "should show out of bounds when page number is too high" do
+    create(2, 3, 2).should be_out_of_bounds
+  end
+    
+  it "should not show out of bounds when inside collection" do
+    create(1, 3, 2).should_not be_out_of_bounds
+  end
+
+  describe "guessing total count" do
+    it "can guess when collection is shorter than limit" do
+      collection = create { |p| p.replace array }
+      collection.total_entries.should == 8
+    end
+    
+    it "should allow explicit total count to override guessed" do
+      collection = create(2, 5, 10) { |p| p.replace array }
+      collection.total_entries.should == 10
+    end
+    
+    it "should not be able to guess when collection is same as limit" do
+      collection = create { |p| p.replace array(5) }
+      collection.total_entries.should be_nil
+    end
+    
+    it "should not be able to guess when collection is empty" do
+      collection = create { |p| p.replace array(0) }
+      collection.total_entries.should be_nil
+    end
+    
+    it "should be able to guess when collection is empty and this is the first page" do
+      collection = create(1) { |p| p.replace array(0) }
+      collection.total_entries.should == 0
+    end
+  end
+
+  it "should raise WillPaginate::InvalidPage on invalid input" do
+    for bad_input in [0, -1, nil, '', 'Schnitzel']
+      Proc.new { create bad_input }.should raise_error(WillPaginate::InvalidPage)
+    end
+  end
+
+  it "should raise Argument error on invalid per_page setting" do
+    Proc.new { create(1, -1) }.should raise_error(ArgumentError)
+  end
+
+  it "should not respond to page_count anymore" do
+    Proc.new { create.page_count }.should raise_error(NoMethodError)
+  end
+
+  private
+  
+    def create(page = 2, limit = 5, total = nil, &block)
+      if block_given?
+        WillPaginate::Collection.create(page, limit, total, &block)
+      else
+        WillPaginate::Collection.new(page, limit, total)
+      end
+    end
+
+    def array(size = 3)
+      Array.new(size)
+    end
+end