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