Kaminari

Gem Kaminari is a clean, powerful, customizable, and sophisticated paginator based on Scope and Engine for modern web app frameworks and ORMs. By default, Kaminari’s pagination helper outputs the HTML5 <nav> tag and furthermore, the helper supports Rails’ unobtrusive Ajax.

Table of contents

1. How to install Kaminari
2. Scopes
   1. The page Scope
   2. The per Scope
3. View Helper
4. Usage

How to install Kaminari

Reminder:

Make sure that your containers are up and running.

In your Gemfile, add gem kaminari.

  gem 'kaminari'

Then run bundle install.

 root@0122:/usr/src/app# bundle install
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
...
Installing kaminari 1.2.2
Bundle complete! 16 Gemfile dependencies, 71 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

Scopes

In here we will try the basic scopes given by the Kaminari.

The page Scope

The scope page will return the nth page of your records.

Reminder:

• Default per_page value is 25.
• Pagination starts at page 1, not at page 0 (page(0) will return the same results as page(1)).
• Kaminari does not add an order to queries. To avoid surprises, you should generally include an order in paginated queries.

Try the page scope:

irb(main):001:0> Post.count                     #=> 35
irb(main):002:0> Post.page(1)                   #=> [#<Post:0x000055b8dfbaeee0 ... >]
irb(main):003:0> Post.page(1).limit_value       #=> 25
irb(main):004:0> Post.page(1).total_pages       #=> 2
irb(main):005:0> Post.page(1).current_page      #=> 1
irb(main):006:0> Post.page(1).next_page         #=> 2
irb(main):007:0> Post.page(2).prev_page         #=> 1
irb(main):008:0> Post.page(1).first_page?       #=> true
irb(main):009:0> Post.page(2).last_page?        #=> true
irb(main):010:0> Post.page(3).out_of_range?     #=> true

The per Scope

The scope per serves as indicator of how many records to show per page. Additionally, you can get the original size of your records by using total_count.

Reminder:

• per scope is only available when you use page scope.
• per scope uses limit internally and will override any use of limit beforehand.

Try the per scope:

irb(main):001:0> Post.count                            #=> 35
irb(main):002:0> posts = Post.limit(5)                 #=> [#<Post:0x000055b8dfbaeee0 ... >]
irb(main):003:0> posts.count                           #=> 5
irb(main):004:0> posts.page(1).per(20).size            #=> 20
irb(main):004:0> posts.page(1).per(20).total_count     #=> 35

View Helper

Call paginate helper to render the pagination.

<%= paginate @users %>

Sample code above will render several ?page=N pagination links surrounded by an HTML5 <nav> tag. The parameter on your controller will be page for page number and per_page for number of records per page.

Usage

Let’s try it out on our Posts and Comments pages. Add the kaminari scope to our index controllers.

# app/controllers/comments_controller.rb

class CommentsController < ApplicationController
  # ...
  def index
-   @comments = @post.comments.includes(:user)
+   @comments = @post.comments.includes(:user).page(params[:page]).per(5)
  end
  # ...
end

# app/controllers/posts_controller.rb

class PostsController < ApplicationController
  # ...
  def index
-   @posts = Post.includes(:categories, :user)
+   @posts = Post.includes(:categories, :user).page(params[:page]).per(5)
  end
  # ...
end

Then add the paginate helper in our comment and post index views.

<!-- app/views/comments/index.html.erb -->

  <!-- ... -->
+ <%= paginate @comments %>
  <%= link_to 'Post List', posts_path %>

<!-- app/views/posts/index.html.erb -->

  <!-- ... -->
+ <%= paginate @posts %>
  <%= link_to 'New', new_post_path %>

Now we already integrated the kaminari in our application.