API documentation

Active Record pagination

page(params[:page])

Sets the Active Record result set to be paginated.

Post.order('created_at DESC').page(params[:page])

per_page(num)

Limits the Active Record result size. This is equivalent to Active Record's limit() method.

Post.order('created_at DESC').page(params[:page]).per_page(10)

If not set, the default value will be read from Post.per_page, which in turn will fall back to WillPaginate.per_page which is 30 by default.

per_page=(num)

Default per-page configuration, either per-model or global.

# for the Post model
class Post
  self.per_page = 10
end

# set per_page globally
WillPaginate.per_page = 10

View template helpers

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.

You should customize the text in the output using I18n instead of using options, if possible. If you need to customize HTML output, you should create your own link renderer.

• :class - CSS class name for the generated DIV (default: "pagination")
• :previous_label - default: "« Previous"
• :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)
• :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)
• :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>

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

• :model - a model class or string name (default: collection.first.class)
• :html - set to false to generate plain text (default: true)

You can customize the output format using I18n.