106 lines
3.7 KiB
Text
106 lines
3.7 KiB
Text
= 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.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
|
== 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 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].
|
|
|