Backwards incompatibility

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.

Here is a list of changes you need to be aware of.

View helper changes

These will_paginate view helper options have changed:

• :prev_label is now :previous_label for consistency
• :separator is now :link_separator for clarity
• the :id => true magic behavior is gone

You can still customize global view options like this:

WillPaginate::ViewHelpers.pagination_options[:next_label] = "Load more"

However, will_paginate now supports i18n so it's best to customize labels and other output via translations in your locale files. This way you support more than one language in your app.

The HTML output of will_paginate has changed slightly:

• the current page markup <span class="current">1</span> is now a more semantic <em class="current">1</em>
• the "prev_page" classname for previous page link is now "previous_page" for consistency

## will_paginate v2.3
<div class="pagination">
  <span class="disabled prev_page">« Previous</span>
  <span class="current">1</span>
  <a href="./?page=2" rel="next">2</a>
  ...

## will_paginate v3.0
<div class="pagination">
  <span class="disabled previous_page">← Previous</span>
  <em class="current">1</em>
  ...

If you use custom link renderer classes in old will_paginate, you'll probably find that they're broken in the new version since LinkRenderer has mostly been rewritten.

You can still create your own link renderers: for instance, in Rails just subclass the WillPaginate::ActionView::LinkRenderer class.

The page_entries_info helper :entry_name parameter has been renamed to :model.

Active Record

The paginated_each method is gone. The built-in find_each is better for iterating through all records in the database:

User.find_each do |user|
  NewsLetter.weekly_deliver(user)
end

Paginating by IDs with the paginate method is not supported anymore:

# not supported anymore
User.paginate([1,3,5,...], :page => 1)

The new method of doing this in Active Record 3 is with new Arel features:

# define such method in your model:
class User
  def self.by_ids(ids)
    where(table[primary_key].in(ids))
  end
end

User.by_ids(user_ids).page(1)

The :finder parameter for the paginate method is not supported anymore.

# not supported anymore
User.paginate(:page => 1, :finder => 'find_custom')

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:

require 'will_paginate/array'