1 | <?php |
---|
2 | |
---|
3 | /** |
---|
4 | * @file |
---|
5 | * Functions to aid in presenting database results as a set of pages. |
---|
6 | */ |
---|
7 | |
---|
8 | /** |
---|
9 | * Perform a paged database query. |
---|
10 | * |
---|
11 | * Use this function when doing select queries you wish to be able to page. The |
---|
12 | * pager uses LIMIT-based queries to fetch only the records required to render a |
---|
13 | * certain page. However, it has to learn the total number of records returned |
---|
14 | * by the query to compute the number of pages (the number of records / records |
---|
15 | * per page). This is done by inserting "COUNT(*)" in the original query. For |
---|
16 | * example, the query "SELECT nid, type FROM node WHERE status = '1' ORDER BY |
---|
17 | * sticky DESC, created DESC" would be rewritten to read "SELECT COUNT(*) FROM |
---|
18 | * node WHERE status = '1' ORDER BY sticky DESC, created DESC". Rewriting the |
---|
19 | * query is accomplished using a regular expression. |
---|
20 | * |
---|
21 | * Unfortunately, the rewrite rule does not always work as intended for queries |
---|
22 | * that already have a "COUNT(*)" or a "GROUP BY" clause, and possibly for |
---|
23 | * other complex queries. In those cases, you can optionally pass a query that |
---|
24 | * will be used to count the records. |
---|
25 | * |
---|
26 | * For example, if you want to page the query "SELECT COUNT(*), TYPE FROM node |
---|
27 | * GROUP BY TYPE", pager_query() would invoke the incorrect query "SELECT |
---|
28 | * COUNT(*) FROM node GROUP BY TYPE". So instead, you should pass "SELECT |
---|
29 | * COUNT(DISTINCT(TYPE)) FROM node" as the optional $count_query parameter. |
---|
30 | * |
---|
31 | * @param $query |
---|
32 | * The SQL query that needs paging. |
---|
33 | * @param $limit |
---|
34 | * The number of query results to display per page. |
---|
35 | * @param $element |
---|
36 | * An optional integer to distinguish between multiple pagers on one page. |
---|
37 | * @param $count_query |
---|
38 | * An SQL query used to count matching records. |
---|
39 | * @param ... |
---|
40 | * A variable number of arguments which are substituted into the query (and |
---|
41 | * the count query) using printf() syntax. Instead of a variable number of |
---|
42 | * query arguments, you may also pass a single array containing the query |
---|
43 | * arguments. |
---|
44 | * @return |
---|
45 | * A database query result resource, or FALSE if the query was not executed |
---|
46 | * correctly. |
---|
47 | * |
---|
48 | * @ingroup database |
---|
49 | */ |
---|
50 | function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) { |
---|
51 | global $pager_page_array, $pager_total, $pager_total_items; |
---|
52 | $page = isset($_GET['page']) ? $_GET['page'] : ''; |
---|
53 | |
---|
54 | // Substitute in query arguments. |
---|
55 | $args = func_get_args(); |
---|
56 | $args = array_slice($args, 4); |
---|
57 | // Alternative syntax for '...' |
---|
58 | if (isset($args[0]) && is_array($args[0])) { |
---|
59 | $args = $args[0]; |
---|
60 | } |
---|
61 | |
---|
62 | // Construct a count query if none was given. |
---|
63 | if (!isset($count_query)) { |
---|
64 | $count_query = preg_replace(array('/SELECT.*?FROM /As', '/ORDER BY .*/'), array('SELECT COUNT(*) FROM ', ''), $query); |
---|
65 | } |
---|
66 | |
---|
67 | // Convert comma-separated $page to an array, used by other functions. |
---|
68 | $pager_page_array = explode(',', $page); |
---|
69 | |
---|
70 | // We calculate the total of pages as ceil(items / limit). |
---|
71 | $pager_total_items[$element] = db_result(db_query($count_query, $args)); |
---|
72 | $pager_total[$element] = ceil($pager_total_items[$element] / $limit); |
---|
73 | $pager_page_array[$element] = max(0, min((int)$pager_page_array[$element], ((int)$pager_total[$element]) - 1)); |
---|
74 | return db_query_range($query, $args, $pager_page_array[$element] * $limit, $limit); |
---|
75 | } |
---|
76 | |
---|
77 | /** |
---|
78 | * Compose a query string to append to pager requests. |
---|
79 | * |
---|
80 | * @return |
---|
81 | * A query string that consists of all components of the current page request |
---|
82 | * except for those pertaining to paging. |
---|
83 | */ |
---|
84 | function pager_get_querystring() { |
---|
85 | static $string = NULL; |
---|
86 | if (!isset($string)) { |
---|
87 | $string = drupal_query_string_encode($_REQUEST, array_merge(array('q', 'page', 'pass'), array_keys($_COOKIE))); |
---|
88 | } |
---|
89 | return $string; |
---|
90 | } |
---|
91 | |
---|
92 | /** |
---|
93 | * Returns HTML for a query pager. |
---|
94 | * |
---|
95 | * Menu callbacks that display paged query results should call theme('pager') to |
---|
96 | * retrieve a pager control so that users can view other results. |
---|
97 | * Format a list of nearby pages with additional query results. |
---|
98 | * |
---|
99 | * @param $tags |
---|
100 | * An array of labels for the controls in the pager. |
---|
101 | * @param $limit |
---|
102 | * The number of query results to display per page. |
---|
103 | * @param $element |
---|
104 | * An optional integer to distinguish between multiple pagers on one page. |
---|
105 | * @param $parameters |
---|
106 | * An associative array of query string parameters to append to the pager links. |
---|
107 | * @param $quantity |
---|
108 | * The number of pages in the list. |
---|
109 | * @return |
---|
110 | * An HTML string that generates the query pager. |
---|
111 | * |
---|
112 | * @ingroup themeable |
---|
113 | */ |
---|
114 | function theme_pager($tags = array(), $limit = 10, $element = 0, $parameters = array(), $quantity = 9) { |
---|
115 | global $pager_page_array, $pager_total; |
---|
116 | |
---|
117 | // Calculate various markers within this pager piece: |
---|
118 | // Middle is used to "center" pages around the current page. |
---|
119 | $pager_middle = ceil($quantity / 2); |
---|
120 | // current is the page we are currently paged to |
---|
121 | $pager_current = $pager_page_array[$element] + 1; |
---|
122 | // first is the first page listed by this pager piece (re quantity) |
---|
123 | $pager_first = $pager_current - $pager_middle + 1; |
---|
124 | // last is the last page listed by this pager piece (re quantity) |
---|
125 | $pager_last = $pager_current + $quantity - $pager_middle; |
---|
126 | // max is the maximum page number |
---|
127 | $pager_max = $pager_total[$element]; |
---|
128 | // End of marker calculations. |
---|
129 | |
---|
130 | // Prepare for generation loop. |
---|
131 | $i = $pager_first; |
---|
132 | if ($pager_last > $pager_max) { |
---|
133 | // Adjust "center" if at end of query. |
---|
134 | $i = $i + ($pager_max - $pager_last); |
---|
135 | $pager_last = $pager_max; |
---|
136 | } |
---|
137 | if ($i <= 0) { |
---|
138 | // Adjust "center" if at start of query. |
---|
139 | $pager_last = $pager_last + (1 - $i); |
---|
140 | $i = 1; |
---|
141 | } |
---|
142 | // End of generation loop preparation. |
---|
143 | |
---|
144 | $li_first = theme('pager_first', (isset($tags[0]) ? $tags[0] : t('« first')), $limit, $element, $parameters); |
---|
145 | $li_previous = theme('pager_previous', (isset($tags[1]) ? $tags[1] : t('â¹ previous')), $limit, $element, 1, $parameters); |
---|
146 | $li_next = theme('pager_next', (isset($tags[3]) ? $tags[3] : t('next âº')), $limit, $element, 1, $parameters); |
---|
147 | $li_last = theme('pager_last', (isset($tags[4]) ? $tags[4] : t('last »')), $limit, $element, $parameters); |
---|
148 | |
---|
149 | if ($pager_total[$element] > 1) { |
---|
150 | if ($li_first) { |
---|
151 | $items[] = array( |
---|
152 | 'class' => 'pager-first', |
---|
153 | 'data' => $li_first, |
---|
154 | ); |
---|
155 | } |
---|
156 | if ($li_previous) { |
---|
157 | $items[] = array( |
---|
158 | 'class' => 'pager-previous', |
---|
159 | 'data' => $li_previous, |
---|
160 | ); |
---|
161 | } |
---|
162 | |
---|
163 | // When there is more than one page, create the pager list. |
---|
164 | if ($i != $pager_max) { |
---|
165 | if ($i > 1) { |
---|
166 | $items[] = array( |
---|
167 | 'class' => 'pager-ellipsis', |
---|
168 | 'data' => 'âŠ', |
---|
169 | ); |
---|
170 | } |
---|
171 | // Now generate the actual pager piece. |
---|
172 | for (; $i <= $pager_last && $i <= $pager_max; $i++) { |
---|
173 | if ($i < $pager_current) { |
---|
174 | $items[] = array( |
---|
175 | 'class' => 'pager-item', |
---|
176 | 'data' => theme('pager_previous', $i, $limit, $element, ($pager_current - $i), $parameters), |
---|
177 | ); |
---|
178 | } |
---|
179 | if ($i == $pager_current) { |
---|
180 | $items[] = array( |
---|
181 | 'class' => 'pager-current', |
---|
182 | 'data' => $i, |
---|
183 | ); |
---|
184 | } |
---|
185 | if ($i > $pager_current) { |
---|
186 | $items[] = array( |
---|
187 | 'class' => 'pager-item', |
---|
188 | 'data' => theme('pager_next', $i, $limit, $element, ($i - $pager_current), $parameters), |
---|
189 | ); |
---|
190 | } |
---|
191 | } |
---|
192 | if ($i < $pager_max) { |
---|
193 | $items[] = array( |
---|
194 | 'class' => 'pager-ellipsis', |
---|
195 | 'data' => 'âŠ', |
---|
196 | ); |
---|
197 | } |
---|
198 | } |
---|
199 | // End generation. |
---|
200 | if ($li_next) { |
---|
201 | $items[] = array( |
---|
202 | 'class' => 'pager-next', |
---|
203 | 'data' => $li_next, |
---|
204 | ); |
---|
205 | } |
---|
206 | if ($li_last) { |
---|
207 | $items[] = array( |
---|
208 | 'class' => 'pager-last', |
---|
209 | 'data' => $li_last, |
---|
210 | ); |
---|
211 | } |
---|
212 | return theme('item_list', $items, NULL, 'ul', array('class' => 'pager')); |
---|
213 | } |
---|
214 | } |
---|
215 | |
---|
216 | |
---|
217 | /** |
---|
218 | * @defgroup pagerpieces Pager pieces |
---|
219 | * @{ |
---|
220 | * Theme functions for customizing pager elements. |
---|
221 | * |
---|
222 | * Note that you should NOT modify this file to customize your pager. |
---|
223 | */ |
---|
224 | |
---|
225 | /** |
---|
226 | * Returns HTML for a "first page" link. |
---|
227 | * |
---|
228 | * @param $text |
---|
229 | * The name (or image) of the link. |
---|
230 | * @param $limit |
---|
231 | * The number of query results to display per page. |
---|
232 | * @param $element |
---|
233 | * An optional integer to distinguish between multiple pagers on one page. |
---|
234 | * @param $parameters |
---|
235 | * An associative array of query string parameters to append to the pager links. |
---|
236 | * @return |
---|
237 | * An HTML string that generates this piece of the query pager. |
---|
238 | * |
---|
239 | * @ingroup themeable |
---|
240 | */ |
---|
241 | function theme_pager_first($text, $limit, $element = 0, $parameters = array()) { |
---|
242 | global $pager_page_array; |
---|
243 | $output = ''; |
---|
244 | |
---|
245 | // If we are anywhere but the first page |
---|
246 | if ($pager_page_array[$element] > 0) { |
---|
247 | $output = theme('pager_link', $text, pager_load_array(0, $element, $pager_page_array), $element, $parameters); |
---|
248 | } |
---|
249 | |
---|
250 | return $output; |
---|
251 | } |
---|
252 | |
---|
253 | /** |
---|
254 | * Returns HTML for a "previous page" link. |
---|
255 | * |
---|
256 | * @param $text |
---|
257 | * The name (or image) of the link. |
---|
258 | * @param $limit |
---|
259 | * The number of query results to display per page. |
---|
260 | * @param $element |
---|
261 | * An optional integer to distinguish between multiple pagers on one page. |
---|
262 | * @param $interval |
---|
263 | * The number of pages to move backward when the link is clicked. |
---|
264 | * @param $parameters |
---|
265 | * An associative array of query string parameters to append to the pager links. |
---|
266 | * @return |
---|
267 | * An HTML string that generates this piece of the query pager. |
---|
268 | * |
---|
269 | * @ingroup themeable |
---|
270 | */ |
---|
271 | function theme_pager_previous($text, $limit, $element = 0, $interval = 1, $parameters = array()) { |
---|
272 | global $pager_page_array; |
---|
273 | $output = ''; |
---|
274 | |
---|
275 | // If we are anywhere but the first page |
---|
276 | if ($pager_page_array[$element] > 0) { |
---|
277 | $page_new = pager_load_array($pager_page_array[$element] - $interval, $element, $pager_page_array); |
---|
278 | |
---|
279 | // If the previous page is the first page, mark the link as such. |
---|
280 | if ($page_new[$element] == 0) { |
---|
281 | $output = theme('pager_first', $text, $limit, $element, $parameters); |
---|
282 | } |
---|
283 | // The previous page is not the first page. |
---|
284 | else { |
---|
285 | $output = theme('pager_link', $text, $page_new, $element, $parameters); |
---|
286 | } |
---|
287 | } |
---|
288 | |
---|
289 | return $output; |
---|
290 | } |
---|
291 | |
---|
292 | /** |
---|
293 | * Returns HTML for a "next page" link. |
---|
294 | * |
---|
295 | * @param $text |
---|
296 | * The name (or image) of the link. |
---|
297 | * @param $limit |
---|
298 | * The number of query results to display per page. |
---|
299 | * @param $element |
---|
300 | * An optional integer to distinguish between multiple pagers on one page. |
---|
301 | * @param $interval |
---|
302 | * The number of pages to move forward when the link is clicked. |
---|
303 | * @param $parameters |
---|
304 | * An associative array of query string parameters to append to the pager links. |
---|
305 | * @return |
---|
306 | * An HTML string that generates this piece of the query pager. |
---|
307 | * |
---|
308 | * @ingroup themeable |
---|
309 | */ |
---|
310 | function theme_pager_next($text, $limit, $element = 0, $interval = 1, $parameters = array()) { |
---|
311 | global $pager_page_array, $pager_total; |
---|
312 | $output = ''; |
---|
313 | |
---|
314 | // If we are anywhere but the last page |
---|
315 | if ($pager_page_array[$element] < ($pager_total[$element] - 1)) { |
---|
316 | $page_new = pager_load_array($pager_page_array[$element] + $interval, $element, $pager_page_array); |
---|
317 | // If the next page is the last page, mark the link as such. |
---|
318 | if ($page_new[$element] == ($pager_total[$element] - 1)) { |
---|
319 | $output = theme('pager_last', $text, $limit, $element, $parameters); |
---|
320 | } |
---|
321 | // The next page is not the last page. |
---|
322 | else { |
---|
323 | $output = theme('pager_link', $text, $page_new, $element, $parameters); |
---|
324 | } |
---|
325 | } |
---|
326 | |
---|
327 | return $output; |
---|
328 | } |
---|
329 | |
---|
330 | /** |
---|
331 | * Returns HTML for a "last page" link. |
---|
332 | * |
---|
333 | * @param $text |
---|
334 | * The name (or image) of the link. |
---|
335 | * @param $limit |
---|
336 | * The number of query results to display per page. |
---|
337 | * @param $element |
---|
338 | * An optional integer to distinguish between multiple pagers on one page. |
---|
339 | * @param $parameters |
---|
340 | * An associative array of query string parameters to append to the pager links. |
---|
341 | * @return |
---|
342 | * An HTML string that generates this piece of the query pager. |
---|
343 | * |
---|
344 | * @ingroup themeable |
---|
345 | */ |
---|
346 | function theme_pager_last($text, $limit, $element = 0, $parameters = array()) { |
---|
347 | global $pager_page_array, $pager_total; |
---|
348 | $output = ''; |
---|
349 | |
---|
350 | // If we are anywhere but the last page |
---|
351 | if ($pager_page_array[$element] < ($pager_total[$element] - 1)) { |
---|
352 | $output = theme('pager_link', $text, pager_load_array($pager_total[$element] - 1, $element, $pager_page_array), $element, $parameters); |
---|
353 | } |
---|
354 | |
---|
355 | return $output; |
---|
356 | } |
---|
357 | |
---|
358 | |
---|
359 | /** |
---|
360 | * Returns HTML for a link to a specific query result page. |
---|
361 | * |
---|
362 | * @param $text |
---|
363 | * The link text. Also used to figure out the title attribute of the link, |
---|
364 | * if it is not provided in $attributes['title']; in this case, $text must |
---|
365 | * be one of the standard pager link text strings that would be generated by |
---|
366 | * the pager theme functions, such as a number or t('« first'). |
---|
367 | * @param $page_new |
---|
368 | * The first result to display on the linked page. |
---|
369 | * @param $element |
---|
370 | * An optional integer to distinguish between multiple pagers on one page. |
---|
371 | * @param $parameters |
---|
372 | * An associative array of query string parameters to append to the pager link. |
---|
373 | * @param $attributes |
---|
374 | * An associative array of HTML attributes to apply to the pager link. |
---|
375 | * @return |
---|
376 | * An HTML string that generates the link. |
---|
377 | * |
---|
378 | * @ingroup themeable |
---|
379 | */ |
---|
380 | function theme_pager_link($text, $page_new, $element, $parameters = array(), $attributes = array()) { |
---|
381 | $page = isset($_GET['page']) ? $_GET['page'] : ''; |
---|
382 | if ($new_page = implode(',', pager_load_array($page_new[$element], $element, explode(',', $page)))) { |
---|
383 | $parameters['page'] = $new_page; |
---|
384 | } |
---|
385 | |
---|
386 | $query = array(); |
---|
387 | if (count($parameters)) { |
---|
388 | $query[] = drupal_query_string_encode($parameters, array()); |
---|
389 | } |
---|
390 | $querystring = pager_get_querystring(); |
---|
391 | if ($querystring != '') { |
---|
392 | $query[] = $querystring; |
---|
393 | } |
---|
394 | |
---|
395 | // Set each pager link title |
---|
396 | if (!isset($attributes['title'])) { |
---|
397 | static $titles = NULL; |
---|
398 | if (!isset($titles)) { |
---|
399 | $titles = array( |
---|
400 | t('« first') => t('Go to first page'), |
---|
401 | t('â¹ previous') => t('Go to previous page'), |
---|
402 | t('next âº') => t('Go to next page'), |
---|
403 | t('last »') => t('Go to last page'), |
---|
404 | ); |
---|
405 | } |
---|
406 | if (isset($titles[$text])) { |
---|
407 | $attributes['title'] = $titles[$text]; |
---|
408 | } |
---|
409 | else if (is_numeric($text)) { |
---|
410 | $attributes['title'] = t('Go to page @number', array('@number' => $text)); |
---|
411 | } |
---|
412 | } |
---|
413 | |
---|
414 | return l($text, $_GET['q'], array('attributes' => $attributes, 'query' => count($query) ? implode('&', $query) : NULL)); |
---|
415 | } |
---|
416 | |
---|
417 | /** |
---|
418 | * @} End of "Pager pieces". |
---|
419 | */ |
---|
420 | |
---|
421 | /** |
---|
422 | * Helper function |
---|
423 | * |
---|
424 | * Copies $old_array to $new_array and sets $new_array[$element] = $value |
---|
425 | * Fills in $new_array[0 .. $element - 1] = 0 |
---|
426 | */ |
---|
427 | function pager_load_array($value, $element, $old_array) { |
---|
428 | $new_array = $old_array; |
---|
429 | // Look for empty elements. |
---|
430 | for ($i = 0; $i < $element; $i++) { |
---|
431 | if (!$new_array[$i]) { |
---|
432 | // Load found empty element with 0. |
---|
433 | $new_array[$i] = 0; |
---|
434 | } |
---|
435 | } |
---|
436 | // Update the changed element. |
---|
437 | $new_array[$element] = (int)$value; |
---|
438 | return $new_array; |
---|
439 | } |
---|