Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for Rails 3
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app/views/kaminari
lib
spec
.document
.gitignore
.rspec
CHANGELOG
Gemfile
Gemfile.lock
LICENSE.txt
README.rdoc
Rakefile
TODO.txt
VERSION
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

  • Fetch the 7th page of the users (per_page = 25 by default)

    User.page(7)

  • Show a lot more users per each page (change the per_page value)

    User.page(7).per(50)

Controllers

  • Typically, your controller code will look like this:

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

Views

  • 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)

    <%= paginate @users, :window => 3 %>

  • Specifing the “outer window” size (1 by default)

    <%= paginate @users, :outer_window => 3 %>

  • outer window can be separetely specified by “left”, “right” (1 by default)

    <%= paginate @users, :left => 0, :right => 2 %>

  • Ajax links (crazy simple, but works perfectly!)

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

Customizing the pagination helper

  • The generator

    % rails g kaminari:views

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.

% rails g kaminari:views -e haml

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.