WillPaginate

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.

Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51], check it out.

Your mind reels with questions? Join our Google group[http://groups.google.com/group/will_paginate].

Installation

Will Paginate officially supports Rails versions 1.2.6 and 2.0.x.

Previously, the plugin was available on the following SVN location:

  svn://errtheblog.com/svn/plugins/will_paginate

In February 2008, it moved to GitHub[http://github.com/mislav/will_paginate/tree] to be tracked with git. The SVN repo continued to have updates, but not forever. Therefore you should switch to using the gem:

  gem install will_paginate

After that, you can remove the plugin from your applications and add a simple require to the end of config/environment.rb:

  require 'will_paginate'

That’s it, just remember to install the gem on all machines that you are deploying to.

The second option is to download and extract the tarball from GitHub. Here is the link for downloading the current state of the master branch: http://github.com/mislav/will_paginate/tarball/master

Extract it to vendor/plugins. The directory will have a default name like "mislav-will_paginate-master"; you can rename it to "will_paginate" for simplicity.

Example usage

Use a paginate finder in the controller:

    @posts = Post.paginate_by_board_id @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. (Copy and paste the example fancy CSS styles from the bottom.) 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
    end

… or like this:

    class Post < ActiveRecord::Base
      def self.per_page
        50
      end
    end

… 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:

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

    <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.

Oh noes, a bug!

Tell us what happened so we can fix it, quick! Issues are filed on the Lighthouse project: http://err.lighthouseapp.com/projects/466-plugins/tickets?q=tagged:will_paginate

Steps to make an awesome bug report:

1. Run rake test in the will_paginate directory. (You will need SQLite3.) Copy the output if there are failing tests.
2. Register on Lighthouse to create a new ticket.
3. Write a descriptive, short title. Provide as much info as you can in the body. Assign the ticket to Mislav and tag it with meaningful tags, "will_paginate" being among them.
4. Yay! You will be notified on updates automatically.

Here is an example of a great bug report and patch: http://err.lighthouseapp.com/projects/466/tickets/172-total_entries-ignored-in-paginate_by_sql

Authors, credits, contact

Want to discuss, request features, ask questions? Join the Google group: http://groups.google.com/group/will_paginate

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é.

Usable pagination in the UI

Copy the following CSS into your stylesheet for a good start:

  .pagination {
    padding: 3px;
    margin: 3px;
  }
  .pagination a {
    padding: 2px 5px 2px 5px;
    margin: 2px;
    border: 1px solid #aaaadd;
    text-decoration: none;
    color: #000099;
  }
  .pagination a:hover, .pagination a:active {
    border: 1px solid #000099;
    color: #000;
  }
  .pagination span.current {
    padding: 2px 5px 2px 5px;
    margin: 2px;
    border: 1px solid #000099;
    font-weight: bold;
    background-color: #000099;
    color: #FFF;
  }
  .pagination span.disabled {
    padding: 2px 5px 2px 5px;
    margin: 2px;
    border: 1px solid #eee;
    color: #ddd;
  }

More reading about pagination as design pattern:

• Pagination 101: http://kurafire.net/log/archive/2007/06/22/pagination-101
• Pagination gallery: http://www.smashingmagazine.com/2007/11/16/pagination-gallery-examples-and-good-practices/
• Pagination on Yahoo Design Pattern Library: http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination