The following blog post contains material either currently found or soon to be incorporated into my new book, "Easy Active Record for Rails Developers". Among many other topics, you'll learn about model generation, migrations, validations, associations, scopes, joins, includes, forms integration, nested forms, and model testing with RSpec and FactoryGirl. The book is now available, head over to this website's home page to learn more.

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!

Like what you read? There’s plenty more where this came from in my new book, “Easy Active Record for Rails Developers”!