Module: WillPaginate::ViewHelpers

Includes:
I18n
Included in:
ActionView, Merb, Sinatra::Helpers
Defined in:
lib/will_paginate/view_helpers.rb,
lib/will_paginate/view_helpers/link_renderer.rb,
lib/will_paginate/view_helpers/link_renderer_base.rb

Overview

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.

Defined Under Namespace

Classes: LinkRenderer, LinkRendererBase

Class Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from I18n

load_path, locale_dir, #will_paginate_translate

Class Attribute Details

+ (Object) pagination_options

Write to this hash to override default options on the global level:

WillPaginate::ViewHelpers.pagination_options[:page_links] = false


19
20
21
# File 'lib/will_paginate/view_helpers.rb', line 19

def pagination_options
  @pagination_options
end

Instance Method Details

- (Object) page_entries_info(collection, options = {})

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.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
# File 'lib/will_paginate/view_helpers.rb', line 103

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.total_entries, :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

- (Object) will_paginate(collection, options = {})

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

  • :class – CSS class name for the generated DIV (default: “pagination”)

  • :previous_label – default: “« Previous”

  • :next_label – default: “Next »”

  • :inner_window – how many links are shown around the current page (default: 4)

  • :outer_window – how many links are around the first and the last page (default: 1)

  • :link_separator – string separator for page HTML elements (default: single space)

  • :param_name – parameter name for page number in URLs (default: :page)

  • :params – additional parameters when generating pagination links (eg. :controller => "foo", :action => nil)

  • :renderer – class name, class or instance of a link renderer (default in Rails: WillPaginate::ActionView::LinkRenderer)

  • :page_links – when false, only previous/next links are rendered (default: true)

  • :container – 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>


71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# File 'lib/will_paginate/view_helpers.rb', line 71

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