Module: ActionController::Pagination

Defined in:
lib/action_controller/pagination.rb

Overview

Action Pack pagination for Active Record collections

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_by => '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_by => '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 nil, 'last_name, first_name', 
            @person_pages.current.to_sql
end

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

Defined Under Namespace

Modules: ClassMethods Classes: Paginator

Constant Summary collapse

OPTIONS =

A hash holding options for controllers using macro-style pagination

Hash.new
DEFAULT_OPTIONS =

The default options for pagination

{
  :class_name => nil,
  :per_page   => 10,
  :conditions => nil,
  :order_by   => nil,
  :join       => nil,
  :parameter  => 'page'
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



74
75
76
77
 
# File 'lib/action_controller/pagination.rb', line 74

def self.included(base) #:nodoc:
  super
  base.extend(ClassMethods)
end

.validate_options!(collection_id, options, in_action) ⇒ Object

:nodoc:

Raises:

  • (ActionController::ActionControllerError) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/action_controller/pagination.rb', line 79

def self.validate_options!(collection_id, options, in_action) #:nodoc:
  options.merge!(DEFAULT_OPTIONS) {|key, old, new| old}

  valid_options = DEFAULT_OPTIONS.keys
  valid_options << :actions unless in_action

  unknown_option_keys = options.keys - valid_options
  raise ActionController::ActionControllerError,
        "Unknown options: #{unknown_option_keys.join(', ')}" unless
          unknown_option_keys.empty?

  options[:singular_name] = Inflector.singularize(collection_id.to_s)
  options[:class_name]  ||= Inflector.camelize(options[:singular_name])
end

Instance Method Details

#paginate(collection_id, options = {}) ⇒ Object

Returns a paginator and a collection of Active Record model instances for the paginator’s current page. This is designed to be used in a single action; to automatically paginate multiple actions, consider ClassMethods#paginate.

options are:

:class_name

the class name to use, if it can’t be inferred by singularizing the collection name

:per_page

the maximum number of items to include in a single page. Defaults to 10

:conditions

optional conditions passed to Model.find_all and Model.count

:order_by

optional order parameter passed to Model.find_all

:join

optional join parameter passed to Model.find_all and Model.count



109
110
111
112
 
# File 'lib/action_controller/pagination.rb', line 109

def paginate(collection_id, options={})
  Pagination.validate_options!(collection_id, options, true)
  paginator_and_collection_for(collection_id, options)
end