= 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.

=== Configuring default per_page value for each model

* paginates_per
You can specify default per_page value per each model using the following declarative DSL.
  class User < ActiveRecord::Base
    paginates_per 50
  end

=== 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 %>

=== I18n and labels

The default labels for 'previous', '...' and 'next' are rendered through I18n API.
So, for example, if you want to change the "prev_label" to '<-', add it to a YAML file in your Rails.root/config/locales directory. Keys and the default values are the following.

  en:
    views:
      pagination:
        previous: "&laquo; Prev"
        next: "Next &raquo;"
        truncate: "..."

=== 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
The generator has the ability to fetch several sample template themes from the external repository (https://github.com/amatsuda/kaminari_themes) in addition to the bundled "default" one, which will help you creating a nice looking paginator.
  % rails g kaminari:views THEME

To see the full list of avaliable themes, take a look at the themes repository, or just hit the generator without specifying THEME argument.
  % rails g kaminari:views


== For more information

Check out Kaminari recipes on the GitHub Wiki for more advanced tips and techniques.
https://github.com/amatsuda/kaminari/wiki/Kaminari-recipes

== 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 (c) 2011 Akira Matsuda. See LICENSE.txt for further details.