= 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 an ActiveRecord model:

  Post.paginate :page => 1, :order => 'created_at DESC'
  
... or this on an ActiveResource model:

  Post.paginate :params => {: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:

* {Installation instructions}[http://github.com/mislav/will_paginate/wikis/installation]
  on {the wiki}[http://github.com/mislav/will_paginate/wikis]
* Your mind reels with questions? Join our
  {Google group}[http://groups.google.com/group/will_paginate].
* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs]


== Example usage

=== ActiveRecord

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. (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 <tt>per_page</tt> 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 <b>30</b> 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.

=== ActiveResource

Use an +ActiveResource+ paginate finder in the client controller:

    @posts = Post.paginate :params => {:board_id => @board.id, :page => params[:page]}

Yeah, +paginate+ works just like +find+ -- it just will paginate the results. If your server returns a standard +to_xml+ from a +find+ on ActiveRecord, then the result will be paginated as an Array. However, querying for all records and only picking out what you want is inefficient. If your server uses WillPaginate, and returns a +to_xml+ from a +paginate+ on ActiveRecord then you will only get what you ask for without doing another "paginate" call on a client-side Array. Don't forget to tell it which page you want, or it will complain!
Read more on WillPaginate::Deserializer::ClassMethods.

Use an +ActiveRecord+ paginate finder in the server controller:

    @posts = Post.paginate_by_board_id @board.id, :page => params[:page], :per_page => params[:per_page]}  
    respond_to do |format|
      format.xml { render :xml => @posts.to_xml }
    end
    
Behind the scenes, the XML generated will be something like:

    <posts type="collection">
      <current-page>1</current-page>
      <per-page>30</per-page>
      <total-entries>1337</total-entries>
      ...
    </posts>
instead of the traditional:

    <posts type="array">
      ...
    </posts>
    
And once again, even if your server does not use WillPaginate your client-side call will still fallback to paginating on the complete resultset +Array+.

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 <tt>per_page</tt> class method. You can define it like this:

    class Post < ActiveResource::Base
      self.site = "http://api.forum.com:3000/"
    
      cattr_reader :per_page
      @@per_page = 50
    end

... or like this:

    class Post < ActiveResource::Base
      self.site = "http://api.forum.com:3000/"
      
      def self.per_page
        50
      end
    end

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

    @posts = Post.paginate :params => {: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 ActiveResource
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::Deserializer::ClassMethods for pagination on your models;
* WillPaginate::ViewHelpers for your views.    


== Authors and credits

Authors::                Mislav Marohnić, PJ Hyett
Original announcement::  http://errtheblog.com/post/929 
Original PHP source::    http://www.strangerstudios.com/sandbox/pagination/diggstyle.php

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}[http://mislav.caboo.se/static/will_paginate/].

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]

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