will_paginate is my gem if choice when it comes to introducing pagination into a Rails application. It’s really easy to setup assuming that you’re going to be paging through Active Record collections.

It’s possible to page through non-ActiveRecord collections but requires slightly different arguments.

Case in point: I’ve got a User model that has_many organizations. When the user is logged into the application, I can reference him/her by using a current_user variable. I can then access the organizations for that user by calling current_user.organizations.

In order to page through that collection, I call:

current_user.organizations.paginate :page => params[:page], :per_page => 5

Specifically, the per_page argument must be passed to the paginate method on the non-ActiveRecord collection in order for the gem to work.