From 51778ef1b34d985c5f3eeb5a3236218f01799d4f Mon Sep 17 00:00:00 2001 From: Dries Buytaert Date: Tue, 26 Nov 2002 19:24:20 +0000 Subject: - Applied Ax's pager patch: includes documentation (rewrote it somewhat) and two bugfixes; one that makes taxanomy based paging work (eg. index.php?and=2,3) and one that kills a warning when the query returns no records. --- includes/pager.inc | 213 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 121 insertions(+), 92 deletions(-) (limited to 'includes') diff --git a/includes/pager.inc b/includes/pager.inc index 17a276b21..a7cb48784 100644 --- a/includes/pager.inc +++ b/includes/pager.inc @@ -1,30 +1,41 @@ +

Implementation note: making queries pagable

+

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 

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; preg_replace("/SELECT.*FROM/i", "SELECT COUNT(*) FROM", $query).

+

Unfortunately, the call to preg_replace() does not work as intended for queries that already have a COUNT() clause; the original COUNT() will be removed from the query, possibly making the remainder of the query fail (eg. when the use of HAVING or ORDER depends on the value returned by COUNT()). In practice, for queries to be db_query_pager()-able, they shold be reformulated not to use COUNT().

+ . -** $limit: how many nodes are displayed per page -** $element: support for multiple pagers per page (specify which -** this is) -** $type: allows for distinction between pagers on main page and -** admin page, etc. Supported types are "default", "admin" -** and "simple". -*/ +/* *************************************************** + * external functions (API) + * ***************************************************/ + +/** + * 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 + */ function pager_display($tags = "", $limit = 10, $element = 0, $type = "default") { return theme_invoke("pager_display_". $type, $tags, $limit, $element); } -/* -** 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. -*/ +/** + * 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 + */ function pager_display_default($tags = "", $limit = 10, $element = 0) { $output .= "
"; $output .= ""; @@ -37,12 +48,14 @@ function pager_display_default($tags = "", $limit = 10, $element = 0) { return "$output"; } -/* -** SIMPLE PAGER: -** When writing themes, if you 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. -*/ +/** + * 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 + */ function pager_display_simple($tags = "", $limit = 10, $element = 0) { /* ** It's left as an exercise to theme writers to create an alternative @@ -52,12 +65,14 @@ function pager_display_simple($tags = "", $limit = 10, $element = 0) { return pager_display_default($tags, $limit, $element); } -/* -** 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. -*/ +/** + * 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 + */ function pager_display_admin($tags = "", $limit = 10, $element = 0) { /* ** It's left as an exercise to theme writers to create an alternative @@ -67,19 +82,18 @@ function pager_display_admin($tags = "", $limit = 10, $element = 0) { return pager_display_default($tags, $limit, $element); } -/********************************************************************* -* 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) -********************************************************************/ - -/* -** pager_first: displays a "first-page" link -** $text: defines the name (or image) of the link -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -*/ +/* ******************************************************************* + * 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) + * *******************************************************************/ + +/** + * displays a "first-page" link + * + * @see pager_previous + */ function pager_first($text, $limit, $element = 0) { global $from_array; @@ -92,13 +106,16 @@ function pager_first($text, $limit, $element = 0) { } } -/* -** pager_previous: displays a "previous-page" link -** $text: defines the name (or image) of the link -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -** $n: how many pages we move back (defaults to 1) -*/ +/** + * 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 + */ function pager_previous($text, $limit, $element = 0, $n = 1) { global $from_array; $from_new = pager_load_array(((int)$from_array[$element] - ((int)$limit * (int)$n)), $element, $from_array); @@ -108,13 +125,11 @@ function pager_previous($text, $limit, $element = 0, $n = 1) { return "$text"; } -/* -** pager_next: displays a "next-page" link -** $text: defines the name (or image) of the link -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -** $n: how many pages we move forward (defaults to 1) -*/ +/** + * displays a "next-page" link + * + * @see pager_previous + */ function pager_next($text, $limit, $element = 0, $n = 1) { global $from_array, $pager_total; $from_new = pager_load_array(((int)$from_array[$element] + ((int)$limit * (int)$n)), $element, $from_array); @@ -124,12 +139,11 @@ function pager_next($text, $limit, $element = 0, $n = 1) { return " "; } -/* -** pager_last: displays a "last-page" link -** $text: defines the name (or image) of the link -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -*/ +/** + * displays a "last-page" link + * + * @see pager_previous + */ function pager_last($text, $limit, $element = 0) { global $from_array, $pager_total; @@ -143,12 +157,12 @@ function pager_last($text, $limit, $element = 0) { return " "; } -/* -** pager_detail: displays "%d through %d of $d" type detail about the cur page -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -** $format: allows you to reword the format string -*/ +/** + * 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 + */ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") { global $from_array, $pager_total; @@ -159,17 +173,17 @@ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") { return $output; } -/* -** pager_list: displays a list of nearby pages with additional nodes -** $limit: how many nodes are displayed per page -** $element: distinguish between multiple pagers on one page -** $quantity: defines the length of the page list -** $text: optional text to display before the page list -*/ +/** + * 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 + */ function pager_list($limit, $element = 0, $quantity = 5, $text = "") { global $from_array, $pager_total; -// calculate various markers within this pager piece: + // calculate various markers within this pager piece: // middle used to "center" pages around current page $pager_middle = ceil((int)$quantity / 2); // offset adds "offset" second page @@ -236,24 +250,39 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "") { } -/********************************************************************* +/* ******************************************************************** * QUERIES - call this instead of db_query() if you want your query to * support a pager. - *********************************************************************/ - -/* -** Use this function when doing select queries you wish to be able to page -** $query, the database query *without* "LIMIT" in it -** examples : "SELECT * FROM table" -** : "SELECT field1,field2 FROM table WHERE nid = '1'" -** $limit, how many rows to return (per page) [OPTIONAL] -** $element, adds support for multiple paged tables on one page [OPTIONAL] -*/ + * ********************************************************************/ + +/** + * Use this function when doing select queries you wish to be able to page. + * + * TODO: + * - remove database dependency ($db_type) piece + * . use db_query_range from + * . rename db_query_pager() to pager_query() + * - examine a better solution for the "no COUNT in $query" requirement (see (output of) {@link pager_help()}) + * + * @param string $query the database query *without* "LIMIT" in it. examples:
+ *   "SELECT * FROM table"
+ *   "SELECT field1,field2 FROM table WHERE nid = '1'"
+ * @param int $limit how many rows to return (per page) + * @param int $element adds support for multiple paged tables on one page + * + * @return resource MySQL query result + */ function db_query_pager($query, $limit = 10, $element = 0) { global $from, $from_array, $db_type, $pager_total; // count the total number of records in this query: - $pager_total[$element] = array_pop(db_fetch_array(db_query(preg_replace("/SELECT.*FROM/i", "SELECT COUNT(*) as count FROM", $query)))); + $array = db_fetch_array(db_query(preg_replace("/SELECT.*FROM/i", "SELECT COUNT(*) FROM", $query))); + if ($array) { + $pager_total[$element] = array_pop($array); + } + else { + $pager_total[$element] = 0; + } // convert comma separated $from to an array, used by other functions: $from_array = explode(",", $from); -- cgit v1.2.3
". pager_first(($tags[0] ? $tags[0] : t("first page")), $limit, $element) ."