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.
will_paginate view helper options have changed:
:id => truemagic 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:
<span class="current">1</span>is now a more semantic
## 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.
:entry_name parameter has been renamed to
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)
: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:
Previously, all objects returned from
paginate methods were of WillPaginate::Collection type. This is no longer true; in Active Record 3, the
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.
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: