hobo_will_paginate 2.1.0

data/lib/will_paginate/view_helpers.rb

@@ -0,0 +1,161 @@
+# encoding: utf-8
+require 'will_paginate/core_ext'
+require 'will_paginate/i18n'
+require 'will_paginate/deprecation'
+
+module WillPaginate
+  # = Will Paginate view helpers
+  #
+  # The main view helper is +will_paginate+. It renders the pagination links
+  # for the given collection. The helper itself is lightweight and serves only
+  # as a wrapper around LinkRenderer instantiation; the renderer then does
+  # all the hard work of generating the HTML.
+  module ViewHelpers
+    class << self
+      # Write to this hash to override default options on the global level:
+      #
+      #   WillPaginate::ViewHelpers.pagination_options[:page_links] = false
+      #
+      attr_accessor :pagination_options
+    end
+
+    # default view options
+    self.pagination_options = Deprecation::Hash.new \
+      :class          => 'pagination',
+      :previous_label => nil,
+      :next_label     => nil,
+      :inner_window   => 4, # links around the current page
+      :outer_window   => 1, # links around beginning and end
+      :link_separator => ' ', # single space is friendly to spiders and non-graphic browsers
+      :param_name     => :page,
+      :params         => nil,
+      :page_links     => true,
+      :container      => true
+
+    label_deprecation = Proc.new { |key, value|
+      "set the 'will_paginate.#{key}' key in your i18n locale instead of editing pagination_options" if defined? Rails
+    }
+    pagination_options.deprecate_key(:previous_label, :next_label, &label_deprecation)
+    pagination_options.deprecate_key(:renderer) { |key, _| "pagination_options[#{key.inspect}] shouldn't be set globally" }
+
+    include WillPaginate::I18n
+
+    # Returns HTML representing page links for a WillPaginate::Collection-like object.
+    # In case there is no more than one page in total, nil is returned.
+    # 
+    # ==== 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>: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>:link_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 in Rails:
+    #   <tt>WillPaginate::ActionView::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)
+    #
+    # 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, :style => 'color:blue' %>
+    #
+    # will result in:
+    #
+    #   <div class="pagination" style="color:blue"> ... </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)
+
+      options[:previous_label] ||= will_paginate_translate(:previous_label) { '&#8592; Previous' }
+      options[:next_label]     ||= will_paginate_translate(:next_label) { 'Next &#8594;' }
+
+      # get the renderer instance
+      renderer = case options[:renderer]
+      when nil
+        raise ArgumentError, ":renderer not specified"
+      when String
+        klass = if options[:renderer].respond_to? :constantize then options[:renderer].constantize
+          else Object.const_get(options[:renderer]) # poor man's constantize
+          end
+        klass.new
+      when Class then options[:renderer].new
+      else options[:renderer]
+      end
+      # render HTML for pagination
+      renderer.prepare collection, options, self
+      renderer.to_html
+    end
+
+    # Renders a message containing number of displayed vs. total entries.
+    #
+    #   <%= page_entries_info @posts %>
+    #   #-> Displaying posts 6 - 12 of 26 in total
+    #
+    # The default output contains HTML. Use ":html => false" for plain text.
+    def page_entries_info(collection, options = {})
+      model = options[:model]
+      model = collection.first.class unless model or collection.empty?
+      model ||= 'entry'
+      model_key = if model.respond_to? :model_name
+                    model.model_name.i18n_key  # ActiveModel::Naming
+                  else
+                    model.to_s.underscore
+                  end
+
+      if options.fetch(:html, true)
+        b, eb = '<b>', '</b>'
+        sp = '&nbsp;'
+        html_key = '_html'
+      else
+        b = eb = html_key = ''
+        sp = ' '
+      end
+
+      model_count = collection.total_pages > 1 ? 5 : collection.size
+      defaults = ["models.#{model_key}"]
+      defaults << Proc.new { |_, opts|
+        if model.respond_to? :model_name
+          model.model_name.human(:count => opts[:count])
+        else
+          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
+      }
+      model_name = will_paginate_translate defaults, :count => model_count
+
+      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
+        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
+    end
+  end
+end

data/lib/will_paginate/view_helpers/action_view.rb

@@ -0,0 +1,148 @@
+require 'will_paginate/view_helpers'
+require 'will_paginate/view_helpers/link_renderer'
+
+module WillPaginate
+  # = ActionView helpers
+  # 
+  # This module serves for availability in ActionView templates. It also adds a new
+  # view helper: +paginated_section+.
+  # 
+  # == Using the helper without arguments
+  # If the helper is called without passing in the collection object, it will
+  # try to read from the instance variable inferred by the controller name.
+  # For example, calling +will_paginate+ while the current controller is
+  # PostsController will result in trying to read from the <tt>@posts</tt>
+  # variable. Example:
+  #
+  #   <%= will_paginate :id => true %>
+  #
+  # ... will result in <tt>@post</tt> collection getting paginated:
+  #
+  #   <div class="pagination" id="posts_pagination"> ... </div>
+  #
+  module ActionView
+    include ViewHelpers
+
+    def will_paginate(collection = nil, options = {}) #:nodoc:
+      options, collection = collection, nil if collection.is_a? Hash
+      collection ||= infer_collection_from_controller
+
+      options = options.symbolize_keys
+      options[:renderer] ||= LinkRenderer
+
+      super(collection, options).try(:html_safe)
+    end
+
+    def page_entries_info(collection = nil, options = {}) #:nodoc:
+      options, collection = collection, nil if collection.is_a? Hash
+      collection ||= infer_collection_from_controller
+
+      super(collection, options.symbolize_keys)
+    end
+
+    # Wrapper for rendering pagination links at both top and bottom of a block
+    # of content.
+    # 
+    #   <% paginated_section @posts do %>
+    #     <ol id="posts">
+    #       <% for post in @posts %>
+    #         <li> ... </li>
+    #       <% end %>
+    #     </ol>
+    #   <% end %>
+    #
+    # will result in:
+    #
+    #   <div class="pagination"> ... </div>
+    #   <ol id="posts">
+    #     ...
+    #   </ol>
+    #   <div class="pagination"> ... </div>
+    #
+    # Arguments are passed to a <tt>will_paginate</tt> call, so the same options
+    # apply. Don't use the <tt>:id</tt> option; otherwise you'll finish with two
+    # blocks of pagination links sharing the same ID (which is invalid HTML).
+    def paginated_section(*args, &block)
+      pagination = will_paginate(*args)
+      if pagination
+        pagination + capture(&block) + pagination
+      else
+        capture(&block)
+      end
+    end
+
+    def will_paginate_translate(keys, options = {})
+      if respond_to? :translate
+        if Array === keys
+          defaults = keys.dup
+          key = defaults.shift
+        else
+          defaults = nil
+          key = keys
+        end
+        translate(key, options.merge(:default => defaults, :scope => :will_paginate))
+      else
+        super
+      end
+    end
+
+    protected
+
+    def infer_collection_from_controller
+      collection_name = "@#{controller.controller_name}"
+      collection = instance_variable_get(collection_name)
+      raise ArgumentError, "The #{collection_name} variable appears to be empty. Did you " +
+        "forget to pass the collection object for will_paginate?" if collection.nil?
+      collection
+    end
+
+    class LinkRenderer < ViewHelpers::LinkRenderer
+      protected
+
+      def default_url_params
+        {}
+      end
+
+      def url(page)
+        @base_url_params ||= begin
+          url_params = merge_get_params(default_url_params)
+          merge_optional_params(url_params)
+        end
+
+        url_params = @base_url_params.dup
+        add_current_page_param(url_params, page)
+
+        @template.url_for(url_params)
+      end
+
+      def merge_get_params(url_params)
+        if @template.respond_to? :request and @template.request and @template.request.get?
+          symbolized_update(url_params, @template.params.except(*@options[:ignore_params]))
+        end
+        url_params
+      end
+
+      def merge_optional_params(url_params)
+        symbolized_update(url_params, @options[:params]) if @options[:params]
+        url_params
+      end
+
+      def add_current_page_param(url_params, page)
+        unless param_name.index(/[^\w-]/)
+          url_params[param_name.to_sym] = page
+        else
+          page_param = parse_query_parameters("#{param_name}=#{page}")
+          symbolized_update(url_params, page_param)
+        end
+      end
+
+      private
+
+      def parse_query_parameters(params)
+        Rack::Utils.parse_nested_query(params)
+      end
+    end
+
+    ::ActionView::Base.send :include, self
+  end
+end

data/lib/will_paginate/view_helpers/link_renderer.rb

@@ -0,0 +1,132 @@
+require 'cgi'
+require 'will_paginate/core_ext'
+require 'will_paginate/view_helpers'
+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[:link_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 ||= @options.except(*(ViewHelpers.pagination_options.keys + [:renderer] - [:class]))
+      end
+      
+    protected
+    
+      def page_number(page)
+        unless page == current_page
+          link(page, page, :rel => rel_value(page))
+        else
+          tag(:em, page, :class => 'current')
+        end
+      end
+      
+      def gap
+        text = @template.will_paginate_translate(:page_gap) { '&hellip;' }
+        %(<span class="gap">#{text}</span>)
+      end
+      
+      def previous_page
+        num = @collection.current_page > 1 && @collection.current_page - 1
+        previous_or_next_page(num, @options[:previous_label], 'previous_page')
+      end
+      
+      def next_page
+        num = @collection.current_page < @collection.total_pages && @collection.current_page + 1
+        previous_or_next_page(num, @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 param_name
+        @options[:param_name].to_s
+      end
+
+      def link(text, target, attributes = {})
+        if target.is_a? Fixnum
+          attributes[:rel] = rel_value(target)
+          target = url(target)
+        end
+        attributes[:href] = target
+        attributes = @options[:extra_attributes].merge(attributes) if @options[:extra_attributes]
+        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.current_page - 1; 'prev' + (page == 1 ? ' start' : '')
+        when @collection.current_page + 1; '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,77 @@
+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 = 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
+        @total_pages ||= @collection.total_pages
+      end
+    end
+  end
+end