= WillPaginate

Pagination is just limiting the number of records displayed. Why should you let
it get in your way while doing more important tasks on your project? This
plugin makes magic happen. Ever wanted to be able to do just this:

  Post.paginate :page => 1

... and then render the page links with a single call to a view helper? Well,
now you can. Simply:

  script/plugin install svn://errtheblog.com/svn/plugins/will_paginate

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


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

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, but 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 %>


== Authors, credits, contact!

REPORT BUGS on Lighthouse:  http://err.lighthouseapp.com/projects/466-plugins/overview

BROWSE SOURCE on Warehouse: http://plugins.require.errtheblog.com/browser/will_paginate

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

  Ruby port by:           PJ Hyett, Mislav Marohnić (Sulien)
  Original announcement:  http://errtheblog.com/post/929 
  Original PHP source:    http://www.strangerstudios.com/sandbox/pagination/diggstyle.php
  Contributors:           Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, 
                          Mike Garey, Bence Golda, Matt Aimonetti, Charles Brian Quinn,
                          Desi McAdam, James Coglan, Matijs van Zuijlen

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