A Scope & Engine based clean and powerful and customizable and sophisticated paginator for Rails 3
-
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.
3.0.x and 3.1
Put this line in your Gemfile:
gem 'kaminari'
Then bundle:
% bundle
-
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.
-
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
-
the page parameter is in params
Typically, your controller code will look like this:
@users = User.order(:name).page params[:page]
-
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.
-
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 %>
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
Feel free to message me on Github (amatsuda) or Twitter (@a_matsuda) ☇☇☇ :)
-
Fork, fix, then send me a pull request.
Copyright © 2011 Akira Matsuda. See LICENSE.txt for further details.