pager.inc 14 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
Dries's avatar
 
Dries committed
2
// $Id$
Dries's avatar
 
Dries committed
3

4
/**
5 6
 * @file
 * Functions to aid in presenting database results as a set of pages.
Dries's avatar
 
Dries committed
7
 */
8 9

/**
10 11
 * Perform a paged database query.
 *
Dries's avatar
 
Dries committed
12 13 14
 * Use this function when doing select queries you wish to be able to page. The
 * pager uses LIMIT-based queries to fetch only the records required to render a
 * certain page. However, it has to learn the total number of records returned
15 16 17 18 19 20
 * by the query to compute the number of pages (the number of records / records
 * per page). This is done by inserting "COUNT(*)" in the original query. For
 * example, the query "SELECT nid, type FROM node WHERE status = '1' ORDER BY
 * sticky DESC, created DESC" would be rewritten to read "SELECT COUNT(*) FROM
 * node WHERE status = '1' ORDER BY sticky DESC, created DESC". Rewriting the
 * query is accomplished using a regular expression.
21
 *
Dries's avatar
 
Dries committed
22
 * Unfortunately, the rewrite rule does not always work as intended for queries
23
 * that already have a "COUNT(*)" or a "GROUP BY" clause, and possibly for
Dries's avatar
 
Dries committed
24 25
 * other complex queries. In those cases, you can optionally pass a query that
 * will be used to count the records.
26
 *
27 28
 * For example, if you want to page the query "SELECT COUNT(*), TYPE FROM node
 * GROUP BY TYPE", pager_query() would invoke the incorrect query "SELECT
Dries's avatar
 
Dries committed
29 30
 * COUNT(*) FROM node GROUP BY TYPE". So instead, you should pass "SELECT
 * COUNT(DISTINCT(TYPE)) FROM node" as the optional $count_query parameter.
31
 *
32 33 34 35 36 37 38 39
 * @param $query
 *   The SQL query that needs paging.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $count_query
 *   An SQL query used to count matching records.
Dries's avatar
 
Dries committed
40 41
 * @param ...
 *   A variable number of arguments which are substituted into the query (and
42 43 44
 *   the count query) using printf() syntax. Instead of a variable number of
 *   query arguments, you may also pass a single array containing the query
 *   arguments.
45 46 47
 * @return
 *   A database query result resource, or FALSE if the query was not executed
 *   correctly.
Dries's avatar
 
Dries committed
48 49
 *
 * @ingroup database
50
 */
Dries's avatar
 
Dries committed
51
function pager_query($query, $limit = 10, $element = 0, $count_query = NULL) {
52
  global $pager_from_array, $pager_total;
53
  $from = $_GET['from'];
54

Dries's avatar
 
Dries committed
55 56 57
  // Substitute in query arguments.
  $args = func_get_args();
  $args = array_slice($args, 4);
58 59 60 61
  // Alternative syntax for '...'
  if (is_array($args[0])) {
    $args = $args[0];
  }
Dries's avatar
 
Dries committed
62

63
  // Construct a count query if none was given.
Dries's avatar
 
Dries committed
64
  if (!isset($count_query)) {
65
    $count_query = preg_replace(array('/SELECT.*?FROM/As', '/ORDER BY .*/'), array('SELECT COUNT(*) FROM', ''), $query);
66 67
  }

68 69
  // Convert comma-separated $from to an array, used by other functions.
  $pager_from_array = explode(',', $from);
70

71 72 73 74 75 76 77
  if (count($args)) {
    $pager_total[$element] = db_result(db_query($count_query, $args));
    return db_query_range($query, $args, (int)$pager_from_array[$element], (int)$limit);
  }
  else {
    $pager_total[$element] = db_result(db_query($count_query));
    return db_query_range($query, (int)$pager_from_array[$element], (int)$limit);
Dries's avatar
 
Dries committed
78
  }
79 80
}

Dries's avatar
 
Dries committed
81
/**
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
 * Format a query pager.
 *
 * Menu callbacks that display paged query results should call theme('pager') to
 * retrieve a pager control so that users can view other results.
 *
 * @param $tags
 *   An array of labels for the controls in the pager.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates the query pager.
Dries's avatar
 
Dries committed
97 98
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
99
 */
100
function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) {
Dries's avatar
Dries committed
101
  global $pager_total;
Dries's avatar
 
Dries committed
102 103
  $output = '';

Dries's avatar
Dries committed
104
  if ($pager_total[$element] > $limit) {
105
    $output .= '<div id="pager" class="container-inline">';
Dries's avatar
 
Dries committed
106 107 108 109 110
    $output .= theme('pager_first', ($tags[0] ? $tags[0] : t('first page')), $limit, $element, $attributes);
    $output .= theme('pager_previous', ($tags[1] ? $tags[1] : t('previous page')), $limit, $element, 1, $attributes);
    $output .= theme('pager_list', $limit, $element, ($tags[2] ? $tags[2] : 9 ), '', $attributes);
    $output .= theme('pager_next', ($tags[3] ? $tags[3] : t('next page')), $limit, $element, 1, $attributes);
    $output .= theme('pager_last', ($tags[4] ? $tags[4] : t('last page')), $limit, $element, $attributes);
111
    $output .= '</div>';
Dries's avatar
 
Dries committed
112

Dries's avatar
Dries committed
113 114
    return $output;
  }
Dries's avatar
 
Dries committed
115
}
116

117
/**
Kjartan's avatar
Kjartan committed
118
 * @name Pager pieces
119
 * @{
Dries's avatar
 
Dries committed
120 121
 * Use these pieces to construct your own custom pagers in your theme. Note that
 * you should NOT modify this file to customize your pager.
122
 */
Dries's avatar
 
Dries committed
123

Dries's avatar
 
Dries committed
124
/**
125
 * Format a "first page" link.
Dries's avatar
 
Dries committed
126
 *
127 128 129 130 131 132 133 134 135 136
 * @param $text
 *   The name (or image) of the link.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
137 138
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
139
 */
Dries's avatar
 
Dries committed
140
function theme_pager_first($text, $limit, $element = 0, $attributes = array()) {
Dries's avatar
 
Dries committed
141
  global $pager_from_array;
142
  $output = '<div class="pager-first">';
Dries's avatar
 
Dries committed
143

Dries's avatar
 
Dries committed
144
  if ($pager_from_array[$element]) {
Dries's avatar
 
Dries committed
145
    $output .= '<a href="'. pager_link(pager_load_array(0, $element, $pager_from_array), $element, $attributes) .'">'. $text .'</a>';
Dries's avatar
 
Dries committed
146 147
  }
  else {
Dries's avatar
 
Dries committed
148
    $output .= ' ';
Dries's avatar
 
Dries committed
149
  }
Dries's avatar
 
Dries committed
150 151
  $output .= '</div>';
  return $output;
Dries's avatar
 
Dries committed
152 153
}

Dries's avatar
 
Dries committed
154
/**
155
 * Format a "previous page" link.
Dries's avatar
 
Dries committed
156
 *
157 158 159 160 161 162 163 164 165 166 167 168
 * @param $text
 *   The name (or image) of the link.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $interval
 *   The number of pages to move backward when the link is clicked.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
169 170
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
171
 */
Dries's avatar
 
Dries committed
172
function theme_pager_previous($text, $limit, $element = 0, $interval = 1, $attributes = array()) {
Dries's avatar
 
Dries committed
173
  global $pager_from_array;
174
  $output = '<div class="pager-previous">';
175
  $from_new = pager_load_array(((int)$pager_from_array[$element] - ((int)$limit * (int)$interval)), $element, $pager_from_array);
Dries's avatar
 
Dries committed
176
  if ($from_new[$element] < 1) {
Dries's avatar
 
Dries committed
177 178 179 180
    $output .= theme('pager_first', $text, $limit, $element, $attributes);
  }
  else {
    $output .= '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
Dries's avatar
 
Dries committed
181
  }
Dries's avatar
 
Dries committed
182 183
  $output .= '</div>';
  return $output;
Dries's avatar
 
Dries committed
184 185
}

Dries's avatar
 
Dries committed
186
/**
187
 * Format a "next page" link.
188
 *
189 190 191 192 193 194 195 196 197 198 199 200
 * @param $text
 *   The name (or image) of the link.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $interval
 *   The number of pages to move forward when the link is clicked.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
201 202
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
203
 */
Dries's avatar
 
Dries committed
204
function theme_pager_next($text, $limit, $element = 0, $interval = 1, $attributes = array()) {
Dries's avatar
 
Dries committed
205
  global $pager_from_array, $pager_total;
206
  $output = '<div class="pager-next">';
207
  $from_new = pager_load_array(((int)$pager_from_array[$element] + ((int)$limit * (int)$interval)), $element, $pager_from_array);
Dries's avatar
 
Dries committed
208
  if ($from_new[$element] < $pager_total[$element]) {
Dries's avatar
 
Dries committed
209 210 211 212
    $output .= '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
  }
  else {
    $output .= ' ';
Dries's avatar
 
Dries committed
213
  }
Dries's avatar
 
Dries committed
214 215
  $output .= '<div>';
  return $output;
Dries's avatar
 
Dries committed
216 217
}

Dries's avatar
 
Dries committed
218
/**
219
 * Format a "last page" link.
Dries's avatar
 
Dries committed
220
 *
221 222 223 224 225 226 227 228 229 230
 * @param $text
 *   The name (or image) of the link.
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
231 232
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
233
 */
Dries's avatar
 
Dries committed
234
function theme_pager_last($text, $limit, $element = 0, $attributes = array()) {
Dries's avatar
 
Dries committed
235
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
236

237
  $output = '<div class="pager-last">';
238 239
  $last_num = (($pager_total[$element] % $limit) ? ($pager_total[$element] % $limit) : $limit);
  $from_new = pager_load_array(($pager_total[$element] - $last_num), $element, $pager_from_array);
Dries's avatar
 
Dries committed
240
  if ($from_new[$element] < ($pager_from_array[$element] + $limit)) {
Dries's avatar
 
Dries committed
241
    $output .= theme('pager_next', $text, $limit, $element, 1, $attributes);
Dries's avatar
 
Dries committed
242
  }
Dries's avatar
 
Dries committed
243 244
  else if (($from_new[$element] > $pager_from_array[$element]) && ($from_new[$element] > 0) && ($from_new[$element] < $pager_total[$element])) {
    $output .= '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
Dries's avatar
 
Dries committed
245
  }
Dries's avatar
 
Dries committed
246 247 248 249 250
  else {
    $output .= ' ';
  }
  $output .= '</div>';
  return $output;
Dries's avatar
 
Dries committed
251 252
}

Dries's avatar
 
Dries committed
253
/**
254
 * Format a summary of the current pager position, such as "6 through 10 of 52".
255
 *
256 257 258 259 260 261 262 263
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $format
 *   A printf-style format string for customizing the pager text.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
264 265
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
266
 */
Dries's avatar
 
Dries committed
267
function theme_pager_detail($limit, $element = 0, $format = '%d through %d of %d.') {
Dries's avatar
 
Dries committed
268
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
269

270
  $output = '<div class="pager-detail">';
Dries's avatar
 
Dries committed
271
  if ($pager_total[$element] > (int)$pager_from_array[$element] + 1) {
Dries's avatar
 
Dries committed
272
    $output .= sprintf($format, (int)$pager_from_array[$element] + 1, ((int)$pager_from_array[$element] + $limit <= $pager_total[$element] ? (int)$pager_from_array[$element] + $limit : $pager_total[$element]), $pager_total[$element]);
Dries's avatar
 
Dries committed
273
  }
Dries's avatar
 
Dries committed
274
  $output .= '</div>';
Dries's avatar
 
Dries committed
275 276 277 278

  return $output;
}

Dries's avatar
 
Dries committed
279
/**
280
 * Format a list of nearby pages with additional query results.
281
 *
282 283 284 285 286 287 288 289 290 291 292 293
 * @param $limit
 *   The number of query results to display per page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $quantity
 *   The number of pages in the list.
 * @param $text
 *   A string of text to display before the page list.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager links.
 * @return
 *   An HTML string that generates this piece of the query pager.
Dries's avatar
 
Dries committed
294 295
 *
 * @ingroup themeable
Dries's avatar
 
Dries committed
296
 */
Dries's avatar
 
Dries committed
297
function theme_pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes = array()) {
Dries's avatar
 
Dries committed
298
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
299

300
  $output = '<div class="pager-list">';
301 302
  // Calculate various markers within this pager piece:
  // Middle is used to "center" pages around the current page.
Dries's avatar
 
Dries committed
303 304
  $pager_middle = ceil((int)$quantity / 2);
  // offset adds "offset" second page
Dries's avatar
 
Dries committed
305
  $pager_offset = (int)$pager_from_array[$element] % (int)$limit;
Dries's avatar
 
Dries committed
306
  // current is the page we are currently paged to
Dries's avatar
 
Dries committed
307
  if (($pager_current = (ceil(($pager_from_array[$element] + 1) / $limit))) < 1) {
Dries's avatar
 
Dries committed
308 309 310 311 312 313
    $pager_current = 1;
  }
  // first is the first page listed by this pager piece (re quantity)
  $pager_first = (int)$pager_current - (int)$pager_middle + 1;
  // last is the last page listed by this pager piece (re quantity)
  $pager_last = (int)$pager_current + (int)$quantity - (int)$pager_middle;
314
  // max is the maximum number of pages content can is divided into
Dries's avatar
 
Dries committed
315 316 317 318 319 320 321 322
  if (!$pager_max = (ceil($pager_total[$element] / $limit))) {
    $pager_max = 1;
  }
  if ((int)$pager_offset) {
    // adjust for offset second page
    $pager_max++;
    $pager_current++;
  }
Dries's avatar
 
Dries committed
323
  // End of marker calculations.
Dries's avatar
 
Dries committed
324

Dries's avatar
 
Dries committed
325
  // Prepare for generation loop.
Dries's avatar
 
Dries committed
326 327
  $i = (int)$pager_first;
  if ($pager_last > $pager_max) {
328
    // Adjust "center" if at end of query.
Dries's avatar
 
Dries committed
329 330 331 332
    $i = $i + (int)($pager_max - $pager_last);
    $pager_last = $pager_max;
  }
  if ($i <= 0) {
333
    // Adjust "center" if at start of query.
Dries's avatar
 
Dries committed
334 335 336
    $pager_last = $pager_last + (1 - $i);
    $i = 1;
  }
Dries's avatar
 
Dries committed
337
  // End of generation loop preparation.
Dries's avatar
 
Dries committed
338

339
  // When there is more than one page, create the pager list.
Dries's avatar
 
Dries committed
340
  if ($i != $pager_max) {
Dries's avatar
 
Dries committed
341
    $output .= $text;
Dries's avatar
 
Dries committed
342
    if ($i > 1) {
343
      $output .= '<div class="pager-list-dots-left>... </div>';
Dries's avatar
 
Dries committed
344
    }
Dries's avatar
 
Dries committed
345

346
    // Now generate the actual pager piece.
Dries's avatar
 
Dries committed
347 348
    for (; $i <= $pager_last && $i <= $pager_max; $i++) {
      if ($i < $pager_current) {
Dries's avatar
 
Dries committed
349
        $output .= theme('pager_previous', $i, $limit, $element, ($pager_current - $i), $attributes) ." ";
Dries's avatar
 
Dries committed
350 351
      }
      if ($i == $pager_current) {
352
        $output .= '<strong>'. $i .'</strong> ';
Dries's avatar
 
Dries committed
353 354
      }
      if ($i > $pager_current) {
Dries's avatar
 
Dries committed
355
        $output .= theme('pager_next', $i, $limit, $element, ($i - $pager_current), $attributes) ." ";
Dries's avatar
 
Dries committed
356
      }
Dries's avatar
 
Dries committed
357 358
    }

Dries's avatar
 
Dries committed
359
    if ($i < $pager_max) {
360
      $output .= '<div class="pager-list-dots-right">...</div>';
Dries's avatar
 
Dries committed
361
    }
Dries's avatar
 
Dries committed
362
  }
Dries's avatar
 
Dries committed
363
  $output .= '</div>';
Dries's avatar
 
Dries committed
364 365 366

  return $output;
}
Dries's avatar
 
Dries committed
367 368 369
/**
 * @} End of "Pager pieces".
 */
Dries's avatar
 
Dries committed
370

371 372 373 374 375 376 377 378 379 380 381 382
/**
 * Format a link to a specific query result page.
 *
 * @param $from_new
 *   The first result to display on the linked page.
 * @param $element
 *   An optional integer to distinguish between multiple pagers on one page.
 * @param $attributes
 *   An associative array of query string parameters to append to the pager link.
 * @return
 *   An HTML string that generates the link.
 */
Dries's avatar
 
Dries committed
383
function pager_link($from_new, $element, $attributes = array()) {
Dries's avatar
 
Dries committed
384 385
  $q = $_GET['q'];
  $from = array_key_exists('from', $_GET) ? $_GET['from'] : '';
Dries's avatar
 
Dries committed
386

Dries's avatar
 
Dries committed
387
  foreach($attributes as $key => $value) {
388
    $query[] = $key .'='. $value;
Dries's avatar
 
Dries committed
389
  }
Dries's avatar
 
Dries committed
390

391
  $from_new = pager_load_array($from_new[$element], $element, explode(',', $from));
Dries's avatar
 
Dries committed
392
  if (count($attributes)) {
393
    $url = url($q, 'from='. implode($from_new, ',') .'&amp;'. implode('&amp;', $query));
Dries's avatar
 
Dries committed
394 395
  }
  else {
396
    $url = url($q, 'from='. implode($from_new, ','));
Dries's avatar
 
Dries committed
397 398
  }

Dries's avatar
 
Dries committed
399
  return $url;
Dries's avatar
 
Dries committed
400 401 402 403
}

function pager_load_array($value, $element, $old_array) {
  $new_array = $old_array;
Dries's avatar
 
Dries committed
404
  // Look for empty elements.
Dries's avatar
 
Dries committed
405 406
  for ($i = 0; $i < $element; $i++) {
    if (!$new_array[$i]) {
Dries's avatar
 
Dries committed
407
      // Load found empty element with 0.
Dries's avatar
 
Dries committed
408 409 410
      $new_array[$i] = 0;
    }
  }
Dries's avatar
 
Dries committed
411
  // Update the changed element.
Dries's avatar
 
Dries committed
412 413 414 415
  $new_array[$element] = (int)$value;
  return $new_array;
}

Dries's avatar
 
Dries committed
416
?>