Most awesome pagination solution for Ruby
Pull request Compare This branch is 15 commits ahead, 410 commits behind mislav:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This fork

I needed to paginate an Atom feed, and didn't want to build it myself (specifically because I'm rendering the same content as HTML, anyway). So this fork adds pagination support for XML, usable in Atom feeds or other XML resource representations.

Usage example:

xml.instruct! :xml, :encoding => “UTF-8” xml.feed :xmlns => '', 'xml:base' => base_uri, 'xml:lang' => 'en-us' do :rel => 'self', :type => 'application/atom+xml', :href => request.url :rel => 'alternate', :type => 'text/html', :href => orders_url will_paginate(@orders, :xml => true, :builder => xml) orders_url xml.title 'Feed for OM order updates' xml.updated Order.maximum(:updated_at).iso8601 for order in @orders do … # render entries end end

This will render something like this:

<?xml version=“1.0” encoding=“UTF-8”?> <feed xmlns=“” xml:lang=“en-us” xml:base=“”> <link type=“application/atom+xml” rel=“self” href=“”/> <link type=“text/html” rel=“alternate” href=“”/> <link rel=“next” href=“/orders.atom?page=3”/> <link rel=“previous” href=“/orders.atom?page=1”/> <id>> <title>Feed for OM order updates</title> <updated>2009-04-07T07:44:56Z</updated>

In other words, use will_paginate as you would use it in HTML (the controller code can stay unchanged), and add the :xml => true option. This will make will_paginate return an XML string representation containing appropriate <link rel=…> elements. Alternatively, you can pass in an XML builder and it will use that instead.

Works with Rails 2.3.2.

Note that my experience with git and GitHub is limited, I'm happy about suggestions on how to make this more useful.

Note I had to comment out one of the original (unrelated) tests because of a problem with SQLite.

Below you'll find the original description of will_paginate.


The original

Pagination is just limiting the number of records displayed. Why should you let it get in your way while developing, then? This plugin makes magic happen. Did you ever want to be able to do just this on a model:

Post.paginate :page => 1, :order => 'created_at DESC'

… and then render the page links with a single view helper? Well, now you can.

Some resources to get you started:

Example usage

Use a paginate finder in the controller:

@posts = Post.paginate_by_board_id, :page => params[:page], :order => 'updated_at DESC'

Yeah, paginate works just like find – it just doesn't fetch all the records. Don't forget to tell it which page you want, or it will complain! Read more on WillPaginate::Finder::ClassMethods.

Render the posts in your view like you would normally do. When you need to render pagination, just stick this in:

<%= will_paginate @posts %>

You're done. (You can find the option list at WillPaginate::ViewHelpers.)

How does it know how much items to fetch per page? It asks your model by calling its per_page class method. You can define it like this:

class Post < ActiveRecord::Base
  cattr_reader :per_page
  @@per_page = 50

… or like this:

class Post < ActiveRecord::Base
  def self.per_page

… or don't worry about it at all. WillPaginate defines it to be 30 by default. But you can always specify the count explicitly when calling paginate:

@posts = Post.paginate :page => params[:page], :per_page => 50

The paginate finder wraps the original finder and returns your resultset that now has some new properties. You can use the collection as you would with any ActiveRecord resultset. WillPaginate view helpers also need that object to be able to render pagination:

  <% for post in @posts -%>
    <li>Render `post` in some nice way.</li>
  <% end -%>

<p>Now let's render us some pagination!</p>
<%= will_paginate @posts %>

More detailed documentation:

  • WillPaginate::Finder::ClassMethods for pagination on your models;

  • WillPaginate::ViewHelpers for your views.

Authors and credits


Mislav Marohnić, PJ Hyett

Original announcement

Original PHP source

All these people helped making will_paginate what it is now with their code contributions or just simply awesome ideas:

Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, Mike Garey, Bence Golda, Matt Aimonetti, Charles Brian Quinn, Desi McAdam, James Coglan, Matijs van Zuijlen, Maria, Brendan Ribera, Todd Willey, Bryan Helmkamp, Jan Berkel, Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris Eppstein, Denis Barushev, Ben Pickles.

Usable pagination in the UI

There are some CSS styles to get you started in the “examples/” directory. They are showcased online here.

More reading about pagination as design pattern:

Want to discuss, request features, ask questions? Join the Google group.