kaminari--kaminari/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

Kaminari includes a handy template generator.

* The default generator

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