diff options
Diffstat (limited to 'includes/pager.inc')
| -rw-r--r-- | includes/pager.inc | 193 |
1 files changed, 111 insertions, 82 deletions
diff --git a/includes/pager.inc b/includes/pager.inc index 602f6e78a..9f371e9bf 100644 --- a/includes/pager.inc +++ b/includes/pager.inc @@ -1,24 +1,84 @@ <?php // $Id$ -/* *************************************************** - * external functions (API) - * ***************************************************/ +/** + @defgroup pager_api Pager API + @{ + + Pager external functions (API). + **/ + +/** + * 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 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. + * + * 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. + * + * 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. + * + * @param $query the SQL query that needs paging + * @param $limit the number of rows per page + * @param $element optional attribute to distringuish between multiple pagers on one page + * @param $count_query an optional SQL query used to count records when rewriting the query would fail + * + * @return SQL query result + */ +function pager_query($query, $limit = 10, $element = 0, $count_query = "") { + global $pager_from_array, $pager_total; + $from = $_GET["from"]; + + // count the total number of records in this query: + 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)); + } + + // convert comma separated $from to an array, used by other functions: + $pager_from_array = explode(",", $from); + + return db_query_range($query, (int)$pager_from_array[$element], (int)$limit); + +} /** * 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. + * @param $tags defines your buttons; text or img. + * @param $limit how many nodes are displayed per page + * @param $element support for multiple pagers per page (specify which this is) + * @param $type allows for distinction between pagers on main page and admin page, etc. * Supported types are "default", "admin" and "simple". + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) * * @return string html of pager */ function pager_display($tags = "", $limit = 10, $element = 0, $type = "default", $attributes = array()) { return theme("pager_display_". $type, $tags, $limit, $element, $attributes); } +/** @} End of defgroup pager_api **/ + +/** + * @addtogroup themeable + * @{ + */ /** * DEFAULT PAGER: @@ -76,18 +136,24 @@ function theme_pager_display_admin($tags = "", $limit = 10, $element = 0, $attri */ return theme_pager_display_default($tags, $limit, $element, $attributes); } +/** @} End of addtogroup themeable **/ -/* ******************************************************************* - * 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) - * *******************************************************************/ +/** + * @name pager pieces + * Use these pieces to construct your own custom pagers in your theme. Note + * that you should NOT modify this file to customize your pager. + * @{ + */ /** * displays a "first-page" link * - * @see pager_previous + * @param $text defines the name (or image) of the link + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) + * + * @return string html of this pager piece */ function pager_first($text, $limit, $element = 0, $attributes = array()) { global $pager_from_array; @@ -104,10 +170,11 @@ function pager_first($text, $limit, $element = 0, $attributes = array()) { /** * 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) + * @param $text defines the name (or image) of the link + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $n how many pages we move back (defaults to 1) + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) * * @return string html of this pager piece */ @@ -123,7 +190,13 @@ function pager_previous($text, $limit, $element = 0, $n = 1, $attributes = array /** * displays a "next-page" link * - * @see pager_previous + * @param $text defines the name (or image) of the link + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $n how many pages we move back (defaults to 1) + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) + * + * @return string html of this pager piece */ function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) { global $pager_from_array, $pager_total; @@ -137,7 +210,12 @@ function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) /** * displays a "last-page" link * - * @see pager_previous + * @param $text defines the name (or image) of the link + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) + * + * @return string html of this pager piece */ function pager_last($text, $limit, $element = 0, $attributes = array()) { global $pager_from_array, $pager_total; @@ -155,8 +233,11 @@ function pager_last($text, $limit, $element = 0, $attributes = array()) { /** * 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 + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $format allows you to reword the format string + * + * @return string html of this pager piece */ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") { global $pager_from_array, $pager_total; @@ -171,9 +252,13 @@ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") { /** * 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 + * @param $limit how many nodes are displayed per page + * @param $element distinguish between multiple pagers on one page + * @param $quantity defines the length of the page list + * @param $text optional text to display before the page list + * @param $attributes extra html attributes for \<a href> (eg. title, onMouseOver, etc.) + * + * @return string html of this pager piece */ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes = array()) { global $pager_from_array, $pager_total; @@ -243,63 +328,7 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes return $output; } - - -/* ******************************************************************** - * 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. - * 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. - * - * 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. - * - * 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. - * - * @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 - */ - -function pager_query($query, $limit = 10, $element = 0, $count_query = "") { - global $pager_from_array, $pager_total; - $from = $_GET["from"]; - - // count the total number of records in this query: - 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)); - } - - // convert comma separated $from to an array, used by other functions: - $pager_from_array = explode(",", $from); - - return db_query_range($query, (int)$pager_from_array[$element], (int)$limit); - -} +/* @} End of member group pager pieces */ function pager_link($from_new, $attributes = array()) { $q = $_GET["q"]; |