The following blog post is adapted from material found in my forthcoming book, “Easy Active Record for Rails Developers”. The book’s companion project is based around a location-based application called ArcadeNomad. ArcadeNomad tracks the locations of vintage 1980’s arcade games hidden within bars, bowling alleys, restaurants, malls, and other places of business. All readers will be given the complete source code to ArcadeNomad! If you’d like to be notified when the book publishes, and even receive a discount code, use the e-mail subscription form located on this page to sign up!

Paginating database results is a standard feature of most web applications, yet isn’t something you’d want to necessarily implement on your own. To do so, you’ll need to first define the desired number of records to be presented per page, and then repeatedly iterate over a portion of the total result set (using limit() and offset()) as the user navigates from one page to the next.

Which reminds me, you’ll also need to create a pagination widget such as that presented below:

pagination widget

Finally, because pagination is likely going to be used throughout a number of different views, you’ll want to bundle the implementation into a reusable solution.

My guess is your eyes are starting to glaze over by this point in the post. Heck, I wrote it and am already starting to lose interest! Fortunately, in the Rails world you’ll almost never have to waste time creating such commonplace features from scratch, because chances are very good somebody has already done the difficult work for you! This is certainly the case with pagination, and a number of fantastic third-party packages (known as gems) at your disposal.

Introducing the will_paginate Gem

My favorite pagination gem is undoubtedly will_paginate, by Mislav Marohnić. To make will_paginate available to your Rails application, add the following line to your project’s Gemfile:

gem 'will_paginate'

Save the Gemfile and run bundle install to make the gem available. Once installed, it’s incredibly easy to begin paginating results. For instance, suppose you wanted to paginate the returned list of arcades located in the state of Ohio. You’ll filter on the Location model’s state attribute (using the where method) returning all records having OH assigned as the state. However, you’ll also take advantage of will_paginate’s paginate() method, chaining it to the query and passing along the page number (via the page key) and desired number of records per page (via the per_page key):

@locations = Location
  .where('state = ?', 'OH')
  .paginate(:page => params[:page], :per_page => 10)
  .order('name asc')

The params[:page] is handled by will_paginate, meaning you don’t have to track the page offset! Further, the pagination widget is even managed for you; just add the following line to your view:

<%= will_paginate @locations %>

Adding this line will produce the very same pagination widget as that presented in the earlier screenshot; of course you’re free to adjust the generated CSS to fit the theme of your particular application.

Today’s post was shorter than those recently published, but perhaps the brevity helps to underscore just how easy it is to paginate your results using will_paginate!