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
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:
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 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
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
@locations = Location .where('state = ?', 'OH') .paginate(:page => params[:page], :per_page => 10) .order('name asc')
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!