2011-02-06 05:28:11 +00:00
= Kaminari
2011-02-05 13:32:10 +00:00
2011-02-06 05:28:11 +00:00
A Scope & Engine based clean and powerful and customizable and sophisticated paginator for Rails 3
2011-02-05 13:32:10 +00:00
2011-02-06 05:28:11 +00:00
== 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
2011-02-07 02:58:53 +00:00
Everything is method chainable with less Hasheritis. You know, that's the Rails 3 way.
2011-02-06 05:28:11 +00:00
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.
2011-02-08 02:58:41 +00:00
* Modern
The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper supports the Rails 3 unobtrusive Ajax.
2011-02-06 05:28:11 +00:00
== Rails versions
3.0.x and 3.1
== Install
Put this line in your Gemfile:
gem 'kaminari'
Then bundle:
% bundle
== Usage
2011-02-07 02:58:53 +00:00
=== Query Basics
2011-02-09 15:29:48 +00:00
* the :page scope
To fetch the 7th page of the users (per_page = 25 by default)
2011-02-07 02:58:53 +00:00
User.page(7)
2011-02-06 05:28:11 +00:00
2011-02-09 15:29:48 +00:00
* the :per scope
To show a lot more users per each page (change the per_page value)
2011-02-07 02:58:53 +00:00
User.page(7).per(50)
2011-02-09 15:29:48 +00:00
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.
2011-02-07 02:58:53 +00:00
2011-02-11 16:20:48 +00:00
=== 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.
2011-02-11 19:30:21 +00:00
class User < ActiveRecord::Base
2011-02-11 16:20:48 +00:00
paginates_per 50
end
2011-02-07 02:58:53 +00:00
=== Controllers
2011-02-05 13:32:10 +00:00
2011-02-09 15:29:48 +00:00
* the page parameter is in params[:page]
Typically, your controller code will look like this:
2011-02-07 02:58:53 +00:00
@users = User.order(:name).page params[:page]
2011-02-06 05:28:11 +00:00
2011-02-07 02:58:53 +00:00
=== Views
2011-02-09 15:29:48 +00:00
* the same old helper method
Just call the "paginate" helper:
2011-02-06 05:28:11 +00:00
<%= paginate @users %>
2011-02-09 15:29:48 +00:00
2011-02-08 02:58:41 +00:00
This will render several "?page=N" pagination links surrounded by an HTML5 <nav> tag.
2011-02-06 05:28:11 +00:00
2011-02-08 02:58:41 +00:00
=== Helper Options
2011-02-06 05:28:11 +00:00
2011-02-09 15:29:48 +00:00
* 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 %>
2011-02-06 05:28:11 +00:00
2011-02-09 15:29:48 +00:00
* 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.
2011-02-06 05:28:11 +00:00
<%= paginate @users, :outer_window => 3 %>
2011-02-08 02:58:41 +00:00
* outer window can be separetely specified by "left", "right" (1 by default)
2011-02-09 15:29:48 +00:00
This would output something like 1 ...(snip)... 18 19 20 while having 20 pages in total.
2011-02-06 05:28:11 +00:00
<%= paginate @users, :left => 0, :right => 2 %>
2011-02-07 12:18:21 +00:00
* Ajax links (crazy simple, but works perfectly!)
2011-02-09 15:29:48 +00:00
This would add data-remote="true" to all the links inside.
2011-02-07 12:18:21 +00:00
<%= paginate @users, :remote => true %>
2011-02-07 02:58:53 +00:00
=== Customizing the pagination helper
2011-02-09 13:06:41 +00:00
Kaminari includes a handy template generator.
2011-02-06 05:28:11 +00:00
2011-02-09 15:29:48 +00:00
* to edit your paginator
Run the generator first,
2011-02-09 13:06:41 +00:00
% rails g kaminari:views default
2011-02-06 05:28:11 +00:00
2011-02-09 15:29:48 +00:00
then edit the partials in your app's app/views/kaminari/ directory.
2011-02-07 02:58:53 +00:00
2011-02-09 15:29:48 +00:00
* for Haml users
2011-02-09 13:06:41 +00:00
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
2011-02-12 19:30:47 +00:00
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.
2011-02-09 13:06:41 +00:00
% rails g kaminari:views THEME
2011-02-12 19:30:47 +00:00
To see the full list of avaliable themes, take a look at the themes repository, or just hit the generator without specifying THEME argument.
2011-02-09 13:06:41 +00:00
% rails g kaminari:views
2011-02-11 22:43:28 +00:00
== For more information
Check out Kaminari recipes on the GitHub Wiki.
https://github.com/amatsuda/kaminari/wiki/Kaminari-recipes
2011-02-09 13:06:41 +00:00
== Questions, Feedbacks
2011-02-07 02:58:53 +00:00
2011-02-09 15:29:48 +00:00
Feel free to message me on Github (amatsuda) or Twitter (@a_matsuda) ☇☇☇ :)
2011-02-07 02:58:53 +00:00
2011-02-06 05:28:11 +00:00
== Contributing to Kaminari
* Fork, fix, then send me a pull request.
== Copyright
2011-02-05 13:32:10 +00:00
2011-02-06 05:28:11 +00:00
Copyright (c) 2011 Akira Matsuda. See LICENSE.txt for further details.
