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

Dries's avatar
   
Dries committed
4
5
6
/* ***************************************************
 *            external functions (API)
 * ***************************************************/
Dries's avatar
 
Dries committed
7

Dries's avatar
   
Dries committed
8
9
10
11
12
13
14
15
16
17
18
/**
 * Use this function in your module or theme to display a pager.
 *
 * @param   array   $tags     defines your buttons; text or img.
 * @param   int     $limit    how many nodes are displayed per page
 * @param   int     $element  support for multiple pagers per page (specify which this is)
 * @param   string  $type     allows for distinction between pagers on main page and admin page, etc.
 *   Supported types are "default", "admin" and "simple".
 *
 * @return  string  html of pager
 */
Dries's avatar
   
Dries committed
19
function pager_display($tags = "", $limit = 10, $element = 0, $type = "default", $attributes = array()) {
20
  return theme("pager_display_". $type, $tags, $limit, $element, $attributes = array());
Dries's avatar
 
Dries committed
21
22
}

Dries's avatar
   
Dries committed
23
24
25
26
27
28
29
30
/**
 * DEFAULT PAGER:
 *  When writing themes, you can rewrite this pager function in your
 *  theme.  This is the most common pager type, and thus the main one
 *  to re-write in your theme.
 *
 * @see pager_display
 */
Dries's avatar
   
Dries committed
31
function pager_display_default($tags = "", $limit = 10, $element = 0, $attributes = array()) {
Dries's avatar
   
Dries committed
32
  $output .= "<div align=\"center\"><table cellpadding=\"10\"><tbody><tr>";
Dries's avatar
   
Dries committed
33
34
35
36
37
  $output .= "<td align=\"center\">". pager_first(($tags[0] ? $tags[0] : t("first page")), $limit, $element, $attributes) ."</td>";
  $output .= "<td align=\"center\">". pager_previous(($tags[1] ? $tags[1] : t("previous page")), $limit, $element, 1, $attributes) ."</td>";
  $output .= "<td align=\"center\">". pager_list($limit, $element, ($tags[2] ? $tags[2] : 9 ), "", $attributes) ."</td>";
  $output .= "<td align=\"center\">". pager_next(($tags[3] ? $tags[3] : t("next page")), $limit, $element, 1, $attributes) ."</td>";
  $output .= "<td align=\"center\">". pager_last(($tags[4] ? $tags[4] : t("last page")), $limit, $element, $attributes) ."</td>";
Dries's avatar
   
Dries committed
38
  $output .= "</tr></tbody></table></div>";
Dries's avatar
 
Dries committed
39
40
41
42

  return "$output";
}

Dries's avatar
   
Dries committed
43
44
45
46
47
48
49
50
/**
 * SIMPLE PAGER:
 *   When writing themes, you can rewrite this pager function in your
 *   theme. Keep in mind that the pager it defines is intended to have
 *   a "simple" look, possibly located in a table or block.
 *
 * @see pager_display
 */
Dries's avatar
   
Dries committed
51
function pager_display_simple($tags = "", $limit = 10, $element = 0, $attributes = array()) {
Dries's avatar
 
Dries committed
52
53
54
55
56
  /*
  ** It's left as an exercise to theme writers to create an alternative
  ** pager for pager_display_simple().  if your theme does not offer a
  ** replacement, the theme.inc pager_display_default() is used.
  */
Dries's avatar
   
Dries committed
57
  return pager_display_default($tags, $limit, $element, $attributes);
Dries's avatar
 
Dries committed
58
59
}

Dries's avatar
   
Dries committed
60
61
62
63
64
65
66
67
/**
 * ADMIN PAGER:
 *   When writing themes, you can rewrite this pager function in your
 *   theme.  Most themes will probably NOT re-write this function, as
 *   admin pages are not normally themed.
 *
 * @see pager_display
 */
Dries's avatar
   
Dries committed
68
function pager_display_admin($tags = "", $limit = 10, $element = 0, $attributes = array()) {
Dries's avatar
 
Dries committed
69
70
71
72
73
  /*
  ** It's left as an exercise to theme writers to create an alternative
  ** pager for pager_display_admin().  if your theme does not offer a
  ** replacement, the pager.inc pager_display_default() is used.
  */
Dries's avatar
   
Dries committed
74
  return pager_display_default($tags, $limit, $element, $attributes);
Dries's avatar
 
Dries committed
75
76
}

Dries's avatar
   
Dries committed
77
78
79
80
81
82
/* *******************************************************************
 * PAGER PIECES:
 *  Use these pieces to construct your own custom pagers (i.e. in
 *  themes).  Note that you should NOT modify this file to customize
 *  your pager)
 * *******************************************************************/
Dries's avatar
 
Dries committed
83

Dries's avatar
   
Dries committed
84
85
86
87
88
/**
 * displays a "first-page" link
 *
 * @see pager_previous
 */
Dries's avatar
   
Dries committed
89
90
function pager_first($text, $limit, $element = 0, $attributes = array()) {
  global $pager_from_array;
Dries's avatar
 
Dries committed
91

Dries's avatar
   
Dries committed
92
93
  if ($pager_from_array[$element]) {
    return "<a href=\"". pager_link(pager_load_array(0, $element, $pager_from_array), $attributes) ."\">$text</a>";
Dries's avatar
 
Dries committed
94
95
96
97
98
99
100
  }
  else {
    // we are already at the first page, return nothing
    return " ";
  }
}

Dries's avatar
   
Dries committed
101
102
103
104
105
106
107
108
109
110
/**
 * displays a "previous-page" link
 *
 * @param   string  $text     defines the name (or image) of the link
 * @param   int     $limit    how many nodes are displayed per page
 * @param   int     $element  distinguish between multiple pagers on one page
 * @param   int     $n        how many pages we move back (defaults to 1)
 *
 * @return  string  html of this pager piece
 */
Dries's avatar
   
Dries committed
111
112
113
function pager_previous($text, $limit, $element = 0, $n = 1, $attributes = array()) {
  global $pager_from_array;
  $from_new = pager_load_array(((int)$pager_from_array[$element] - ((int)$limit * (int)$n)), $element, $pager_from_array);
Dries's avatar
 
Dries committed
114
  if ($from_new[$element] < 1) {
Dries's avatar
   
Dries committed
115
    return pager_first($text, $limit, $element, $attributes);
Dries's avatar
 
Dries committed
116
  }
Dries's avatar
   
Dries committed
117
  return "<a href=\"". pager_link($from_new, $attributes) ."\">$text</a>";
Dries's avatar
 
Dries committed
118
119
}

Dries's avatar
   
Dries committed
120
121
122
123
124
/**
 * displays a "next-page" link
 *
 * @see pager_previous
 */
Dries's avatar
   
Dries committed
125
126
127
function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) {
  global $pager_from_array, $pager_total;
  $from_new = pager_load_array(((int)$pager_from_array[$element] + ((int)$limit * (int)$n)), $element, $pager_from_array);
Dries's avatar
 
Dries committed
128
  if ($from_new[$element] < $pager_total[$element]) {
Dries's avatar
   
Dries committed
129
    return "<a href=\"". pager_link($from_new, $attributes) ."\">$text</a>";
Dries's avatar
 
Dries committed
130
131
132
133
  }
  return " ";
}

Dries's avatar
   
Dries committed
134
135
136
137
138
/**
 * displays a "last-page" link
 *
 * @see pager_previous
 */
Dries's avatar
   
Dries committed
139
140
function pager_last($text, $limit, $element = 0, $attributes = array()) {
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
141

Dries's avatar
   
Dries committed
142
143
144
  $from_new = pager_load_array(($pager_total[$element] - $limit), $element, $pager_from_array);
  if ($from_new[$element] < ($pager_from_array[$element] + $limit)) {
    return pager_next($text, $limit, $element, 1, $attributes);
Dries's avatar
 
Dries committed
145
  }
Dries's avatar
   
Dries committed
146
147
  if (($from_new[$element] > $pager_from_array[$element]) && ($from_new[$element] > 0) && $from_new[$element] < $pager_total[$element]) {
    return "<a href=\"". pager_link($from_new, $attributes) ."\">$text</a>";
Dries's avatar
 
Dries committed
148
149
150
151
  }
  return " ";
}

Dries's avatar
   
Dries committed
152
153
154
155
156
157
/**
 * displays "%d through %d of $d" type detail about the cur page
 *
 * @param   string  $format   allows you to reword the format string
 * @see pager_previous
 */
Dries's avatar
 
Dries committed
158
function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") {
Dries's avatar
   
Dries committed
159
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
160

Dries's avatar
   
Dries committed
161
162
  if ($pager_total[$element] > (int)$pager_from_array[$element] + 1) {
    $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
163
164
165
166
167
  }

  return $output;
}

Dries's avatar
   
Dries committed
168
169
170
171
172
173
174
/**
 * displays a list of nearby pages with additional nodes
 *
 * @param   int     $quantity   defines the length of the page list
 * @param   string  $text       optional text to display before the page list
 * @see pager_previous
 */
Dries's avatar
   
Dries committed
175
176
function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes = array()) {
  global $pager_from_array, $pager_total;
Dries's avatar
 
Dries committed
177

Dries's avatar
   
Dries committed
178
  // calculate various markers within this pager piece:
Dries's avatar
 
Dries committed
179
180
181
  // middle used to "center" pages around current page
  $pager_middle = ceil((int)$quantity / 2);
  // offset adds "offset" second page
Dries's avatar
   
Dries committed
182
  $pager_offset = (int)$pager_from_array[$element] % (int)$limit;
Dries's avatar
 
Dries committed
183
  // current is the page we are currently paged to
Dries's avatar
   
Dries committed
184
  if (($pager_current = (ceil(($pager_from_array[$element] + 1) / $limit))) < 1) {
Dries's avatar
 
Dries committed
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
    $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;
  // max is the maximum number of pages content can is devided into
  if (!$pager_max = (ceil($pager_total[$element] / $limit))) {
    $pager_max = 1;
  }
  if ((int)$pager_offset) {
    // adjust for offset second page
    $pager_max++;
    $pager_current++;
  }
// end of various marker calculations

// prepare for generation loop
  $i = (int)$pager_first;
  if ($pager_last > $pager_max) {
    // adjust "center" if at end of query
    $i = $i + (int)($pager_max - $pager_last);
    $pager_last = $pager_max;
  }
  if ($i <= 0) {
    // adjust "center" if at start of query
    $pager_last = $pager_last + (1 - $i);
    $i = 1;
  }
// end of generation loop preparation

Dries's avatar
   
Dries committed
216
217
218
219
220
  // when there is more than one page, create the pager list
  if ($i != $pager_max) {
    $output = "$text";
    if ($i > 1) {
      $output .= "... ";
Dries's avatar
 
Dries committed
221
    }
Dries's avatar
   
Dries committed
222
223
224
225

    // finally we're ready to generate the actual pager piece
    for (; $i <= $pager_last && $i <= $pager_max; $i++) {
      if ($i < $pager_current) {
Dries's avatar
   
Dries committed
226
        $output .= pager_previous($i, $limit, $element, ($pager_current - $i), $attributes) ." ";
Dries's avatar
   
Dries committed
227
228
229
230
231
      }
      if ($i == $pager_current) {
        $output .= "<b>$i</b> ";
      }
      if ($i > $pager_current) {
Dries's avatar
   
Dries committed
232
        $output .= pager_next($i, $limit, $element, ($i - $pager_current), $attributes) ." ";
Dries's avatar
   
Dries committed
233
      }
Dries's avatar
 
Dries committed
234
235
    }

Dries's avatar
   
Dries committed
236
237
238
    if ($i < $pager_max) {
      $output .= "...";
    }
Dries's avatar
 
Dries committed
239
240
241
242
243
244
  }

  return $output;
}


Dries's avatar
   
Dries committed
245
/* ********************************************************************
Dries's avatar
 
Dries committed
246
247
 * QUERIES - call this instead of db_query() if you want your query to
 * support a pager.
Dries's avatar
   
Dries committed
248
 * ********************************************************************/
Dries's avatar
 
Dries committed
249

Dries's avatar
   
Dries committed
250
251
/**
 * Use this function when doing select queries you wish to be able to page.
Dries's avatar
Dries committed
252
253
254
255
256
257
258
259
260
 * 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 by the query to (among others) compute the number
 * of pages (= number of all records / number of records per page).  This
 * is done by inserting "COUNT(*)" in the original query, ie. by rewriting
 * the original query, say "SELECT nid, type FROM node WHERE status = '1'
 * ORDER BY static DESC, created DESC" to read "SELECT COUNT(*) FROM node
 * WHERE status = '1' ORDER BY static DESC, created DESC".  Rewriting the
 * query is accomplished using a regular expression.
Dries's avatar
   
Dries committed
261
 *
Dries's avatar
Dries committed
262
263
264
265
 * Unfortunately, the rewrite rule does not always work as intended for
 * queries that (already) have a "COUNT(*)" or a "GROUP BY" clause, and
 * possibly for other complex queries.  In those cases, you can optionally
 * pass a query that will be used to count the records.
Dries's avatar
   
Dries committed
266
 *
Dries's avatar
Dries committed
267
268
269
270
271
 * For example, if you want to page this query: "SELECT COUNT(*), TYPE FROM
 * node GROUP BY TYPE", pager_query() would invoke the wrong query, being:
 * "SELECT COUNT(*) FROM node GROUP BY TYPE".  So instead, you should pass
 * "SELECT COUNT(DISTINCT(TYPE)) FROM node" as the optional $count_query
 * parameter.
Dries's avatar
   
Dries committed
272
 *
Dries's avatar
Dries committed
273
274
275
276
277
278
 * @param   string  $query        the SQL query that needs paging
 * @param   int     $limit        the number of rows per page
 * @param   int     $element      optional attribute to distringuish between multiple pagers on one page
 * @param   string  $count_query  an optional SQL query used to count records when rewriting the query would fail
 *
 * @return  resource  SQL query result
Dries's avatar
   
Dries committed
279
 */
Dries's avatar
Dries committed
280
281

function pager_query($query, $limit = 10, $element = 0, $count_query = "") {
Dries's avatar
   
Dries committed
282
  global $from, $pager_from_array, $db_type, $pager_total;
Dries's avatar
 
Dries committed
283
284

  // count the total number of records in this query:
Dries's avatar
Dries committed
285
286
287
288
289
290
  if ($count_query == "") {
    $pager_total[$element] = db_result(db_query(preg_replace(array("/SELECT.*FROM/i", "/ORDER BY .*/"), array("SELECT COUNT(*) FROM", ""), $query)));
  }
  else {
    $pager_total[$element] = db_result(db_query($count_query));
  }
Dries's avatar
 
Dries committed
291
292

  // convert comma separated $from to an array, used by other functions:
Dries's avatar
   
Dries committed
293
  $pager_from_array = explode(",", $from);
Dries's avatar
 
Dries committed
294

Dries's avatar
   
Dries committed
295
  return db_query_range($query, (int)$pager_from_array[$element], (int)$limit);
Dries's avatar
 
Dries committed
296
297
}

Dries's avatar
   
Dries committed
298
function pager_link($from_new, $attributes = array()) {
Dries's avatar
Dries committed
299
  global $q;
Dries's avatar
   
Dries committed
300

Dries's avatar
   
Dries committed
301
302
  foreach($attributes as $key => $value) {
    $query[] = "$key=$value";
Dries's avatar
 
Dries committed
303
  }
Dries's avatar
   
Dries committed
304
305

  if (count($attributes)) {
Dries's avatar
   
Dries committed
306
    $url = url($q, "from=". $from_new[0] ."&amp;". implode("&amp;", $query));
Dries's avatar
   
Dries committed
307
308
  }
  else {
Dries's avatar
Dries committed
309
    $url = url($q, "from=". $from_new[0]);
Dries's avatar
   
Dries committed
310
311
  }

Dries's avatar
   
Dries committed
312
  return $url;
Dries's avatar
 
Dries committed
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
}

function pager_load_array($value, $element, $old_array) {
  $new_array = $old_array;
  // look for empty elements
  for ($i = 0; $i < $element; $i++) {
    if (!$new_array[$i]) {
      // load found empty element with 0
      $new_array[$i] = 0;
    }
  }
  // update the changed element
  $new_array[$element] = (int)$value;
  return $new_array;
}

?>