h2. ActionPack PaginationHelper for ActiveRecord collections

table{background-color: #9f9; border: 2px solid #3c6; padding: 5px; display: block; margin-bottom:4ex}.
| "View the RDoc documentation":http://rails.rubyonrails.com/classes/ActionController/Pagination.html |

The Pagination module aids in the process of paging large collections of Active Record objects. It offers macro-style automatic fetching of your model for multiple views, or explicit fetching for single actions. And if the magic isn’t flexible enough for your needs, you can create your own paginators with a minimal amount of code.

The Pagination module can handle as much or as little as you wish. In the controller, have it automatically query your model for pagination; or, if you prefer, create Paginator objects yourself.

Pagination is included automatically for all controllers.

h3. Controller examples

PaginationHelper can handle as much or as little as you wish. In the controller, have it automatically query your model for pagination; or, if you prefer, create Paginator objects yourself.

h4. Automatic pagination for every action in a controller

<pre><code>  class PersonController < ApplicationController
    paginate :people, :order_by => 'last_name, first_name',
             :per_page => 20

    # ...
  end
</code></pre>

Each action in this controller now has access to a @people instance variable, which is an ordered collection of model objects for the current page (at most 20, sorted by last name and first name), and a @person_pages Paginator instance. The current page is determined by the @params['page'] variable.

h4. Pagination for a single action

<pre><code>  def list
    @person_pages, @people =
      paginate :people, :order_by => 'last_name, first_name'
  end
</code></pre>

Like the previous example, but explicitly creates @person_pages and @people for a single action, and uses the default of 10 items per page.

h4. Custom/"classic" pagination

<pre><code>  def list
    @person_pages = Paginator.new self, People.count, 10, @params['page']
    @person = People.find_all nil, 'last_name, first_name',
              @person_pages.current.to_sql
  end
</code></pre>

Explicitly creates the paginator from the previous example and uses Paginator#to_sql to retrieve @people from the model.

h3. View examples

Paginator Helper includes various methods to help you display pagination links in your views. (For information on displaying the paginated collections you retrieve in the controller, see the documentation for ActionView::Partials#render_partial_collection.)

h4. Using Paginator#pagination_links

Use the basic_html method to get a simple list of pages (always including the first and last page) with a window around the current page. In your view, using one of the controller examples above,

<pre><code>  <%= pagination_links(@person_pages) %>
</code></pre>

will render a list of links. For a list of parameters, see the documentation for Page#pagination_links.

h4. Using a paginator partial

If you need more advanced control over pagination links and need to paginate multiple actions and controllers, consider using a shared paginator partial. For instance, _why suggests this partial, which you might place in app/views/partial/_paginator.rhtml:

<pre><code> <div class="counter">
   Displaying <%= paginator.current.first_item %>
   - <%= paginator.current.last_item %>
   of <%= paginator.item_count %>    

   <%= link_to(h('< Previous'), {:page => paginator.current.previous})  + " | " if paginator.current.previous %>
   <%=pagination_links(paginator, :window_size => 4) %>
   <%= " | " + link_to(h('Next >'), {:page => paginator.current.next}) if paginator.current.next %>
 </div>
</code></pre>

Then in your views, simply call

<pre><code>  <%= render_partial "partial/paginator", @person_pages %>
</code></pre>

wherever you want your pagination links to appear.

h4. Using a paginator partial and passing params


*NOTE:* 

Passing params to a paginator partial is currently broken due to the removal of the .to_link method. If anyone has a good/clean solution to this, please replace the following here.

Your view which requires pagination may be based on a search where parameters are required to be passed through the URL each time. You can do this without much hassle by using this partial, based on the above:

*NOTE:*

The following only works with ActionPack < 1.7.0

<pre><code> <div class="counter">
    Displaying <%= paginator[0].current.first_item %>
    - <%= paginator[0].current.last_item %>
    of <%= paginator[0].item_count %>    

    <%= link_to(h('< Previous'), {:page => paginator.current.previous}) + " | " if paginator.current.previous  %>
    <%= pagination_links(paginator[0], :window_size => 4) %>
    <%= " | " + link_to(h('Next >'), {:page => paginator.current.next}) if paginator.current.next  %>
</div>
</code></pre>

Then in your views, render the partial and attach any parameters required, like so:

<pre><code>  <%= render_partial "partial/paginator", [@person_pages, { "q" => @q, "sort_by" => @sort_by }] %>
</code></pre>

<hr />

*NOTE:*
I have a simpler work around for the pagination/parameter problem:
<code>
<% @params.delete('page') %>
<%= pagination_links paginator, :params => @params %>
</code>

<hr />
*Questions:*
Q: How can I jump to a page in code? By QueryString? By Link?

Q: I think the pagination helper doesn't work with components, since you have to prefix the model with the component name and my error messages insist that it can't find these. Am I right or am I doing something wrong?

Q: How can i add some 'GET' - parameters to pagination_links?

A:  e.g u want to add /controller?type='foo' : 

 <pre><code><%= link_to(h('<<'), {:page => paginator.current.previous, :type => @type})  + " | " if paginator.current.previous %>
   <%=pagination_links(paginator, :window_size => 4, :params => { 'type' => @type } ) %>
   <%= " | " + link_to(h('>>'), {:page => paginator.current.next, :type => @type}) if paginator.current.next %></code></pre>

*Credits:*

The PaginationHelper was written by SamStephenson and incorporated into ActionPack 1.6.0

category:Helper