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 LinkRenderer instantiation; the renderer then does all the hard work of generating the HTML.
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 override default options on the global level:
WillPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous page'
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.
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 with the :entry_name parameter:
<%= page_entries_info @posts, :entry_name => 'item' %> #-> Displaying items 6 - 10 of 26 in total
# File lib/will_paginate/view_helpers.rb, line 167 def page_entries_info(collection, options = {}) entry_name = options[:entry_name] || (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' ')) if collection.total_pages < 2 case collection.size when 0; "No #{entry_name.pluralize} found" when 1; "Displaying <b>1</b> #{entry_name}" else; "Displaying <b>all #{collection.size}</b> #{entry_name.pluralize}" end else %{Displaying #{entry_name.pluralize} <b>%d - %d</b> of <b>%d</b> in total} % [ collection.offset + 1, collection.offset + collection.length, collection.total_entries ] end 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 will_paginate call, so the same options apply. Don’t use the :id option; otherwise you’ll finish with two blocks of pagination links sharing the same ID (which is invalid HTML).
# File lib/will_paginate/view_helpers.rb, line 142 def paginated_section(*args, &block) pagination = will_paginate(*args).to_s unless ActionView::Base.respond_to? :erb_variable concat pagination yield concat pagination else content = pagination + capture(&block) + pagination concat(content, block.binding) end end
Renders Digg/Flickr-style pagination for a WillPaginate::Collection object. Nil is returned if there is only one page in total; no point in rendering the pagination in that case…
Display options:
:previous_label – default: “« Previous” (this parameter is called :prev_label in versions 2.3.2 and older!)
:next_label – default: “Next »”
:page_links -- when false, only previous/next links are rendered (default: true)
: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)
:separator -- string separator for page HTML elements (default: single space)
HTML options:
:class -- CSS class name for the generated DIV (default: "pagination")
:container -- toggles rendering of the DIV container for pagination links, set to false only when you are rendering your own pagination markup (default: true)
:id -- 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".
Advanced options:
: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: WillPaginate::LinkRenderer)
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 => 'font-size: small' %>
… will result in:
<div class="pagination" style="font-size: small"> ... </div>
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 @posts variable. Example:
<%= will_paginate :id => true %>
… will result in @post collection getting paginated:
<div class="pagination" id="posts_pagination"> ... </div>
# File lib/will_paginate/view_helpers.rb, line 89 def will_paginate(collection = nil, options = {}) options, collection = collection, nil if collection.is_a? Hash unless collection or !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?" unless collection end # early exit if there is nothing to render 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", caller) options[:previous_label] = options.delete(:prev_label) end # get the renderer instance renderer = case options[:renderer] when String options[:renderer].to_s.constantize.new when Class options[:renderer].new else options[:renderer] end # render HTML for pagination renderer.prepare collection, options, self renderer.to_html end
Generated with the Darkfish Rdoc Generator 2.