forked from mislav/will_paginate
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
152 lines (113 loc) · 4.94 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
= 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.
Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51],
check it out.
Your mind reels with questions? Join our Google
group[http://groups.google.com/group/will_paginate].
You can find more documentation on the wiki[http://github.com/mislav/will_paginate/wikis].
== 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. (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
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.
== Oh noes, a bug!
Tell us what happened so we can fix it, quick! Issues are filed on the Lighthouse project:
http://err.lighthouseapp.com/projects/466-plugins/tickets?q=tagged:will_paginate
Steps to make an awesome bug report:
1. Run <tt>rake test</tt> in the <i>will_paginate</i> directory. (You will need SQLite3.)
Copy the output if there are failing tests.
2. Register on Lighthouse to create a new ticket.
3. Write a descriptive, short title. Provide as much info as you can in the body.
Assign the ticket to Mislav and tag it with meaningful tags, <tt>"will_paginate"</tt>
being among them.
4. Yay! You will be notified on updates automatically.
Here is an example of a great bug report and patch:
http://err.lighthouseapp.com/projects/466/tickets/172-total_entries-ignored-in-paginate_by_sql
== Authors, credits, contact
Want to discuss, request features, ask questions? Join the Google group:
http://groups.google.com/group/will_paginate
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 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.
== Usable pagination in the UI
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;
}
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