mailr/vendor/plugins/will_paginate/README.rdoc

= WillPaginate

Pagination is just limiting the number of records displayed. Why should you let it get in your way
while developing?

This is how you paginate on an ActiveRecord model:

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

Most of the time it's as simple as replacing "find" with "paginate" and specifying the page you want.

Some resources to get you started:

* The {will_paginate project page}[http://github.com/mislav/will_paginate];
* 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];
* {Watch the will_paginate screencast}[http://railscasts.com/episodes/51] by Ryan Bates.


== Installation

The recommended way is that you get the gem:

  gem install --source=http://gems.github.com/ mislav-will_paginate

After that you don't need the will_paginate <i>plugin</i> in your Rails application anymore. In
<b>Rails 2.1</b>, add a gem dependency:

  config.gem 'mislav-will_paginate', :lib => 'will_paginate', :version => '~> 2.5'

If you're using Rails 2.0 or older, just add a simple require to the end of your
"config/environment.rb" instead:

  gem 'mislav-will_paginate', '~> 2.5'
  require 'will_paginate'

That's it. Remember to install the gem on <b>all</b> machines that you are deploying to.

<i>There are extensive {installation
instructions}[http://github.com/mislav/will_paginate/wikis/installation] on {the
wiki}[http://github.com/mislav/will_paginate/wikis].</i>


== 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 about WillPaginate::Finders.

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 < 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. 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 result set that now has some new
properties. You can use the collection as you would use any other array. 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::Finders 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.


== Usable pagination in the UI

There are some CSS styles to get you started in the "examples/" directory. They are showcased in the
<b>"examples/index.html"</b> file.

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/] featured on Smashing Magazine;
* {Pagination design pattern}[http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination] on Yahoo Design Pattern Library.

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