Gem of the Week: will_paginate

September 2, 2016 Jamey Alea 0 Comments

Breaking out long lists into multiple pages that a user can click through is something that nearly every application can benefit from and it’s something that every programmer will have to implement dozens of times in their life. Whenever I think about implementing pagination, it’s second nature for me to add will_paginate into my gemfile and be done with it. It’s one of those gems that I use so much that I don’t even think about it anymore. Why would I do it any other way when this way is so quick and easy?

The simplest implementation of will_paginate only takes two additional steps after you bundle install it. First, go to the controller and find the action that includes the list of items that you want to be paginated. Let’s say the line where you set the instance variable looks like this.

@articles = Article.all

There are a couple different ways you can alter that in order to implement the pagination.

@articles = Article.paginate(:page => params[:page])
@articles = Article.page(params[:page])

These are two different syntaxes that accomplish the same thing, with the second being a newer addition to the gem that only works in Active Record 3 and higher.

The default number of items per page is 30, but you can control that too.

@articles = Article.paginate(:page => params[:page], :per_page => 15)
@articles = Article.page(params[:page]).per_page(15)

You can also set a new default for a particular model by setting it in the model class like this.

self.per_page = 15

Don’t worry, you can chain the paginate method with any other methods and queries that you’d normally be using.

@articles = Article.where(:display => true).order('created_at DESC').paginate(:page => params[:page])

The second step is to go to your view where you are displaying the list that you want to paginate. Right before the code that shows the list, add this line of code.

<% will_paginate @articles %>

This will automatically cause the list to display just the first page of results, with links at the bottom to view other pages or go forward and back. If you only want Next and Previous buttons without showing a list of the page numbers, you can add this param.

<% will_paginate @articles, :page_links => false %>

You can change the wording on the labels with params as well, although they will default to “<< Previous” and “Next >>”.

<% will_paginate @articles, :next_label => “See More”, :previous_label => “Go Back” %>

It can also accept most regular params, like :class and :style.

If you want to be really fancy, you can swap out the Next and Previous buttons with icons by setting them in your config/locales/en.yml file with code that looks like this example.

will_paginate:
    previous_label: <span class="glyph glyph-prev"></span>
    next_label: <span class="glyph glyph-next"></span>

And of course, you can change the design of the whole link set using CSS. The creators of the gem have some great examples here.

Gems are great for taking common programming tasks and making them so easy that you don’t even have to think about them. Letting gems do the easy stuff for you is one of the best things about working with ruby and will_paginate is a great example of that.

(This article was originally published on Uptime.)