[b354002] | 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 | /** |
---|
[d7a822e] | 93 | * Returns HTML for a query pager. |
---|
[b354002] | 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 | /** |
---|
[d7a822e] | 226 | * Returns HTML for a "first page" link. |
---|
[b354002] | 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 | /** |
---|
[d7a822e] | 254 | * Returns HTML for a "previous page" link. |
---|
[b354002] | 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 | /** |
---|
[d7a822e] | 293 | * Returns HTML for a "next page" link. |
---|
[b354002] | 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 | /** |
---|
[d7a822e] | 331 | * Returns HTML for a "last page" link. |
---|
[b354002] | 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 | /** |
---|
[d7a822e] | 360 | * Returns HTML for a link to a specific query result page. |
---|
[b354002] | 361 | * |
---|
[d7a822e] | 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'). |
---|
[b354002] | 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 |
---|
[d7a822e] | 374 | * An associative array of HTML attributes to apply to the pager link. |
---|
[b354002] | 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 | } |
---|