Working With Rails

will_paginate

Quick quiz: Where does pagination logic belong?

a) in the model;
b) in the controller;
c) in views;
d) all of the above.

We think you know the answer (if you think hard enough).

This plugin makes magic happen. You will paginate!

1. Example usage:

Use a paginate finder in the controller:

@posts = Post.paginate_by_board_id @board.id, :page => params[:page]

Yeah, `paginate` works just like `find`—it just doesn’t fetch all the records. Just don’t forget to tell it which page you want!

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

How does it know how much items to fetch per page? It asks your model by calling `Post.per_page`. 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 if missing.) You can also specify the count explicitly when calling `paginate`:

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

Find more options in sections below.

1. Details

The `paginate` finder wraps the original finder and returns a PaginatedCollection instance that’s in fact a proxy to the original collection. You can use the collection as you would any ActiveRecord resultset, but WillPaginate view helpers also need the object to know how to make pagination:

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

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

In model finders, “all” is implicit. No sense in paginating a single record, right?

• Post.paginate => Post.find :all
• Post.paginate_all_by_something => Post.find_all_by_something
• Post.paginate_by_something => Post.find_all_by_something

Options for `paginate` finders are:

• page (default 1)
• per_page (default is read from the model, which is 30 if not overriden)
• total entries: ActiveRecord knows how to count, but you can still override it
• count: takes place of “select” for count() statement
• distinct: also just for count() statement

Options for `will_paginate` view helper:

• class: CSS class name for the generated DIV (default “pagination”)
• prev_label: default ’« Previous’,
• next_label: default ‘Next »’,
• inner_window: how many links are shown around the current page, defaults to 4
• outer_window: how many links are around the first and the last page, defaults to 1

1. Authors, credits

Ruby port by: PJ Hyett, Mislav Marohnić (Sulien) Contributors: K. Adam Christensen, Chris Wanstrath, Dr. Nic Williams Original announcement: http://errtheblog.com/post/929 Original PHP source: http://www.strangerstudios.com/sandbox/pagination/diggstyle.php

1. Want Digg style?

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; }

NOTE: This description has been extracted from the Plugin README and so the formatting may need updating to make browser friendly

Homepage: http://github.com/mislav/will_paginate/wikis