ActionController::Pagination

Action Pack pagination for Active Record collections

DEPRECATION WARNING: Pagination will be moved to a plugin in Rails 2.0. Install the classic_pagination plugin for forward compatibility:

  script/plugin install svn://errtheblog.com/svn/plugins/classic_pagination

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.

For help rendering pagination links, see ActionView::Helpers::PaginationHelper.

Automatic pagination for every action in a controller

  class PersonController < ApplicationController
    model :person

    paginate :people, :order => 'last_name, first_name',
             :per_page => 20

    # ...
  end

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.

Pagination for a single action

  def list
    @person_pages, @people =
      paginate :people, :order => 'last_name, first_name'
  end

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

Custom/"classic" pagination

  def list
    @person_pages = Paginator.new self, Person.count, 10, params[:page]
    @people = Person.find :all, :order => 'last_name, first_name',
                          :limit  =>  @person_pages.items_per_page,
                          :offset =>  @person_pages.current.offset
  end

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