Clone this wiki locally

will_paginate 3.0 is a complete rewrite of the will_paginate 2.3 version. Most of the basic usage of will_paginate has remained the same to preserve backwards compatibility as much as possible, but some things have changed in ways that might break your Rails app when upgrading.

Also, Active Record dynamic paginating finders such as paginate_by_name are not supported anymore. Instead, use the new scope features:

User.scoped_by_name('mislav').page(1)

WillPaginate::Collection

Previously, all objects returned from paginate methods were of WillPaginate::Collection type. This is no longer true; in Active Record 3, the paginate and page methods return a Relation that is extended to look like a WillPaginate::Collection. Similarly, DataMapper returns a regular DataMapper::Collection that is also extended.

Both ActiveRecord::Relation and DataMapper::Collection are lazy arrays in the way that they don't execute any SQL queries until the point when data is needed. This makes them better than ordinary arrays.

The WillPaginate::Collection class is still available, however, and mostly unchanged.

The Array#paginate method still exists, too, but is not loaded by default. If you need to paginate static arrays, first require it in your code: