Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for Rails 3

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 app
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .document
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rspec
Octocat-spinner-32 CHANGELOG
Octocat-spinner-32 Gemfile
Octocat-spinner-32 Gemfile.lock
Octocat-spinner-32 LICENSE.txt
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 TODO.txt
Octocat-spinner-32 VERSION
Octocat-spinner-32 kaminari.gemspec
README.rdoc

Kaminari

A Scope & Engine based clean and powerful and customizable and sophisticated paginator for Rails 3

Features

  • Clean

Does not globally pollute Array, Hash, Object or AR::Base.

  • Easy to use

Just bundle the gem, then your models are ready to be paginated. No configuration. Don't have to define anything in your models or helpers.

  • Scope based simple API

Everything is method chainable with less Hasheritis. You know, that's the Rails 3 way. No special collection class or something for the paginated values but uses a general AR::Relation instance. So, of course you can chain any other conditions before or after the paginator scope.

  • Engine based customizable helper

As the whole pagination helper is basically just a collection of links and non-links, Kaminari renders each of them through its own partial template inside the Engine. So, you can easily modify their behaviour or style or whatever by overriding partial templates.

  • Modern

The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper supports the Rails 3 unobtrusive Ajax.

Rails versions

3.0.x and 3.1

Install

Put this line in your Gemfile:

gem 'kaminari'

Then bundle:

% bundle

Usage

Query Basics

  • the :page scope

To fetch the 7th page of the users (per_page = 25 by default)

User.page(7)
  • the :per scope

To show a lot more users per each page (change the per_page value)

User.page(7).per(50)

Note that the :per scope is not directly defined on the models but is just a method defined on the page scope. This is absolutely reasonable because you will never actually use “per_page” without specifying the “page” number.

Controllers

  • the page parameter is in params[:page]

Typically, your controller code will look like this:

@users = User.order(:name).page params[:page]

Views

  • the same old helper method

Just call the “paginate” helper:

<%= paginate @users %>

This will render several “?page=N” pagination links surrounded by an HTML5 <nav> tag.

Helper Options

  • specifing the “inner window” size (4 by default)

This would output something like … 5 6 7 8 9 … when 7 is the current page.

<%= paginate @users, :window => 2 %>
  • specifing the “outer window” size (1 by default)

This would output something like 1 2 3 4 …(snip)… 17 18 19 20 while having 20 pages in total.

<%= paginate @users, :outer_window => 3 %>
  • outer window can be separetely specified by “left”, “right” (1 by default)

This would output something like 1 …(snip)… 18 19 20 while having 20 pages in total.

<%= paginate @users, :left => 0, :right => 2 %>
  • Ajax links (crazy simple, but works perfectly!)

This would add data-remote=“true” to all the links inside.

<%= paginate @users, :remote => true %>

Customizing the pagination helper

Kaminari includes a handy template generator.

  • to edit your paginator

Run the generator first,

% rails g kaminari:views default

then edit the partials in your app's app/views/kaminari/ directory.

  • for Haml users

Haml templates generator is also available by adding “-e haml” option (this would actually be automatically invoked while the default template_engine is set to Haml).

% rails g kaminari:views default -e haml
  • themes

Kaminari is shipped with template themes in addition to the “default” one, which will help you creating a nice looking paginator.

% rails g kaminari:views THEME

To see the full list of avaliable themes, just hit the generator without specifying THEME argument.

% rails g kaminari:views

Questions, Feedbacks

Feel free to message me on Github (amatsuda) or Twitter (@a_matsuda) ☇☇☇ :)

Contributing to Kaminari

  • Fork, fix, then send me a pull request.

Copyright

Copyright © 2011 Akira Matsuda. See LICENSE.txt for further details.

Something went wrong with that request. Please try again.