Index: includes/bootstrap.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/bootstrap.inc,v retrieving revision 1.18 diff -u -F^function -r1.18 bootstrap.inc --- includes/bootstrap.inc 13 Jul 2004 07:21:14 -0000 1.18 +++ includes/bootstrap.inc 21 Jul 2004 15:42:55 -0000 @@ -3,7 +3,6 @@ /** * @file - * * Functions that need to be loaded on every Drupal request. */ Index: includes/common.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/common.inc,v retrieving revision 1.369 diff -u -F^function -r1.369 common.inc --- includes/common.inc 21 Jul 2004 15:30:35 -0000 1.369 +++ includes/common.inc 21 Jul 2004 15:42:55 -0000 @@ -3,7 +3,6 @@ /** * @file - * * Common functions that many Drupal modules will need to reference. * * The functions that are critical and need to be available even when serving @@ -760,7 +759,10 @@ function search_type($type, $action = NU return search_form($action, $keys, $options) . '
'. search_data($keys); } -/* @} */ + +/** + * @} end of defgroup search + */ function check_form($text) { return drupal_specialchars($text, ENT_QUOTES); @@ -1004,6 +1006,8 @@ function format_name($object) { /** * @defgroup form Form generation * @{ + * + * */ /** @@ -1446,7 +1450,10 @@ function form_weight($title = NULL, $nam return form_select($title, $name, $value, $weights, $description, $extra); } -/* @} */ + +/** + * @} end of defgroup form + */ /** * Generate an internal Drupal URL. Index: includes/menu.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/menu.inc,v retrieving revision 1.56 diff -u -F^function -r1.56 menu.inc --- includes/menu.inc 15 Jul 2004 17:16:58 -0000 1.56 +++ includes/menu.inc 21 Jul 2004 15:42:55 -0000 @@ -2,6 +2,11 @@ /* $Id: menu.inc,v 1.56 2004/07/15 17:16:58 dries Exp $ */ /** + * @file + * API for the Drupal menu system. + */ + +/** * @defgroup menu Menu system * @{ * @@ -493,7 +498,9 @@ function menu_rebuild() { _menu_build(); } -/** @} end of "menu" function group */ +/** + * @} end of defgroup menu + */ /** * @addtogroup themeable @@ -591,7 +598,9 @@ function theme_menu_local_task($mid, $ac } } -/** @} End of addtogroup themeable */ +/** + * @} end of addtogroup themeable + */ /** * Returns an array with the menu items that lead to the current menu item. Index: includes/module.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/module.inc,v retrieving revision 1.53 diff -u -F^function -r1.53 module.inc --- includes/module.inc 14 Jul 2004 20:42:20 -0000 1.53 +++ includes/module.inc 21 Jul 2004 15:42:56 -0000 @@ -2,6 +2,11 @@ // $Id: module.inc,v 1.53 2004/07/14 20:42:20 dries Exp $ /** + * @file + * API for loading and interacting with Drupal modules. + */ + +/** * Initialize all modules. * * To change the required set of modules, change this function as well as Index: includes/pager.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/pager.inc,v retrieving revision 1.28 diff -u -F^function -r1.28 pager.inc --- includes/pager.inc 2 Jul 2004 18:46:40 -0000 1.28 +++ includes/pager.inc 21 Jul 2004 15:42:56 -0000 @@ -2,62 +2,64 @@ // $Id: pager.inc,v 1.28 2004/07/02 18:46:40 dries Exp $ /** - * @defgroup pager Pager interface - * @{ - * - * Pager external functions (API). + * @file + * Functions to aid in presenting database results as a set of pages. */ /** + * Perform a paged database query. + * @ingroup database + * * 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 sticky DESC, created DESC" to read - * "SELECT COUNT(*) FROM node WHERE status = '1' ORDER BY sticky DESC, created - * DESC". Rewriting the query is accomplished using a regular expression. + * 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. * * 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 + * 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 + * 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 * 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 distinguish 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 + * @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. + * @return + * A database query result resource, or FALSE if the query was not executed + * correctly. */ -function pager_query($query, $limit = 10, $element = 0, $count_query = "") { +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/is", "/ORDER BY .*/"), array("SELECT COUNT(*) FROM", ""), $query))); + $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/is', '/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); + // 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 defgroup pager_api */ /** * @addtogroup themeable @@ -65,26 +67,42 @@ function pager_query($query, $limit = 10 */ /** - * When writing themes, you can rewrite this pager function in your theme. - * You need to call theme("pager", ...) to get a pager. + * 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. */ -function theme_pager($tags = "", $limit = 10, $element = 0, $attributes = array()) { +function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) { global $pager_total; $output = ''; if ($pager_total[$element] > $limit) { - $output .= "
"; - $output .= "
". pager_first(($tags[0] ? $tags[0] : t("first page")), $limit, $element, $attributes) ."
"; - $output .= "
". pager_previous(($tags[1] ? $tags[1] : t("previous page")), $limit, $element, 1, $attributes) ."
"; - $output .= "
". pager_list($limit, $element, ($tags[2] ? $tags[2] : 9 ), "", $attributes) ."
"; - $output .= "
". pager_next(($tags[3] ? $tags[3] : t("next page")), $limit, $element, 1, $attributes) ."
"; - $output .= "
". pager_last(($tags[4] ? $tags[4] : t("last page")), $limit, $element, $attributes) ."
"; - $output .= "
"; + $output .= '
'; + $output .= '
'. pager_first(($tags[0] ? $tags[0] : t('first page')), $limit, $element, $attributes) .'
'; + $output .= '
'. pager_previous(($tags[1] ? $tags[1] : t('previous page')), $limit, $element, 1, $attributes) .'
'; + $output .= '
'. pager_list($limit, $element, ($tags[2] ? $tags[2] : 9 ), '', $attributes) .'
'; + $output .= '
'. pager_next(($tags[3] ? $tags[3] : t('next page')), $limit, $element, 1, $attributes) .'
'; + $output .= '
'. pager_last(($tags[4] ? $tags[4] : t('last page')), $limit, $element, $attributes) .'
'; + $output .= '
'; return $output; } } -/** @} End of addtogroup themeable */ + +/** + * @} end of addtogroup themeable + */ /** * @name Pager pieces @@ -94,80 +112,94 @@ function theme_pager($tags = "", $limit */ /** - * displays a "first-page" link + * Format a "first page" link. * - * @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 \ (eg. title, - * onMouseOver, etc.) - * - * @return string html of this pager piece + * @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. */ function pager_first($text, $limit, $element = 0, $attributes = array()) { global $pager_from_array; if ($pager_from_array[$element]) { - return "$text"; + return ''. $text .''; } else { - // we are already at the first page, return nothing - return " "; + // We are already at the first page, so return nothing. + return ' '; } } /** - * displays a "previous-page" link - * - * @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 \ (eg. title, - * onMouseOver, etc.) + * Format a "previous page" link. * - * @return string html of this pager piece + * @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. */ -function pager_previous($text, $limit, $element = 0, $n = 1, $attributes = array()) { +function pager_previous($text, $limit, $element = 0, $interval = 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); + $from_new = pager_load_array(((int)$pager_from_array[$element] - ((int)$limit * (int)$interval)), $element, $pager_from_array); if ($from_new[$element] < 1) { return pager_first($text, $limit, $element, $attributes); } - return "$text"; + return ''. $text .''; } /** - * displays a "next-page" link - * - * @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 \ (eg. title, - * onMouseOver, etc.) + * Format a "next page" link. * - * @return string html of this pager piece + * @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. */ -function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) { +function pager_next($text, $limit, $element = 0, $interval = 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); + $from_new = pager_load_array(((int)$pager_from_array[$element] + ((int)$limit * (int)$interval)), $element, $pager_from_array); if ($from_new[$element] < $pager_total[$element]) { - return "$text"; + return ''. $text .''; } - return " "; + return ' '; } /** - * displays a "last-page" link + * Format a "last page" link. * - * @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 \ (eg. title, - * onMouseOver, etc.) - * - * @return string html of this pager piece + * @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. */ function pager_last($text, $limit, $element = 0, $attributes = array()) { global $pager_from_array, $pager_total; @@ -177,22 +209,26 @@ function pager_last($text, $limit, $elem return pager_next($text, $limit, $element, 1, $attributes); } if (($from_new[$element] > $pager_from_array[$element]) && ($from_new[$element] > 0) && $from_new[$element] < $pager_total[$element]) { - return "$text"; + return ''. $text .''; } - return " "; + return ' '; } /** - * displays "%d through %d of $d" type detail about the cur page - * - * @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 + * Format a summary of the current pager position, such as "6 through 10 of 52". * - * @return string html of this pager piece + * @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. */ -function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") { +function pager_detail($limit, $element = 0, $format = '%d through %d of %d.') { global $pager_from_array, $pager_total; + $output = ''; 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]); @@ -202,22 +238,26 @@ function pager_detail($limit, $element = } /** - * displays a list of nearby pages with additional nodes - * - * @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 \ (eg. title, - * onMouseOver, etc.) + * Format a list of nearby pages with additional query results. * - * @return string html of this pager piece + * @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. */ -function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes = array()) { +function pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes = array()) { global $pager_from_array, $pager_total; - // calculate various markers within this pager piece: - // middle used to "center" pages around current page + // Calculate various markers within this pager piece: + // Middle is used to "center" pages around the current page. $pager_middle = ceil((int)$quantity / 2); // offset adds "offset" second page $pager_offset = (int)$pager_from_array[$element] % (int)$limit; @@ -238,36 +278,36 @@ function pager_list($limit, $element = 0 $pager_max++; $pager_current++; } -// end of various marker calculations +// End of marker calculations. -// prepare for generation loop +// Prepare for generation loop. $i = (int)$pager_first; if ($pager_last > $pager_max) { - // adjust "center" if at end of query + // 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 + // Adjust "center" if at start of query. $pager_last = $pager_last + (1 - $i); $i = 1; } -// end of generation loop preparation +// End of generation loop preparation. - // when there is more than one page, create the pager list + // When there is more than one page, create the pager list. if ($i != $pager_max) { - $output = "$text"; + $output = $text; if ($i > 1) { - $output .= "... "; + $output .= '... '; } - // finally we're ready to generate the actual pager piece + // Now generate the actual pager piece. for (; $i <= $pager_last && $i <= $pager_max; $i++) { if ($i < $pager_current) { $output .= pager_previous($i, $limit, $element, ($pager_current - $i), $attributes) ." "; } if ($i == $pager_current) { - $output .= "$i "; + $output .= ''. $i .' '; } if ($i > $pager_current) { $output .= pager_next($i, $limit, $element, ($i - $pager_current), $attributes) ." "; @@ -275,7 +315,7 @@ function pager_list($limit, $element = 0 } if ($i < $pager_max) { - $output .= "..."; + $output .= '...'; } } @@ -283,20 +323,32 @@ function pager_list($limit, $element = 0 } /* @} End of member group pager pieces */ +/** + * 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. + */ function pager_link($from_new, $element, $attributes = array()) { $q = $_GET['q']; $from = array_key_exists('from', $_GET) ? $_GET['from'] : ''; foreach($attributes as $key => $value) { - $query[] = "$key=$value"; + $query[] = $key .'='. $value; } - $from_new = pager_load_array($from_new[$element], $element, explode("," ,$from)); + $from_new = pager_load_array($from_new[$element], $element, explode(',', $from)); if (count($attributes)) { - $url = url($q, "from=". implode($from_new, ",") ."&". implode("&", $query)); + $url = url($q, 'from='. implode($from_new, ',') .'&'. implode('&', $query)); } else { - $url = url($q, "from=". implode($from_new, ",")); + $url = url($q, 'from='. implode($from_new, ',')); } return $url; Index: includes/tablesort.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/tablesort.inc,v retrieving revision 1.23 diff -u -F^function -r1.23 tablesort.inc --- includes/tablesort.inc 27 Jun 2004 16:02:31 -0000 1.23 +++ includes/tablesort.inc 21 Jul 2004 15:42:56 -0000 @@ -1,6 +1,17 @@ $cell['data'])); - $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('title' => $title), "sort=". $ts['sort']. "&order=". urlencode($cell['data']). $ts['query_string']); + $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('title' => $title), 'sort="'. $ts['sort'] .'&order='. urlencode($cell['data']). $ts['query_string']); unset($cell['field'], $cell['sort']); } return $cell; } +/** + * Format a table cell. + * + * Adds a class attribute to all cells in the currently active column. + * + * @param $cell + * The cell to format. + * @param $header + * An array of column headers in the format described in theme_table(). + * @param $ts + * The current table sort context as returned from tablesort_init(). + * @param $i + * The index of the cell's table column. + * @return + * A properly formatted cell, ready for _theme_table_cell(). + */ function tablesort_cell($cell, $header, $ts, $i) { if ($header[$i]['data'] == $ts['name'] && $header[$i]['field']) { if (is_array($cell)) { @@ -56,6 +120,13 @@ function tablesort_cell($cell, $header, return $cell; } +/** + * Compose a query string to append to table sorting requests. + * + * @return + * A query string that consists of all components of the current page request + * except for those pertaining to table sorting. + */ function tablesort_get_querystring() { $cgi = $_SERVER['REQUEST_METHOD'] == 'GET' ? $_GET : $_POST; foreach ($cgi as $key => $val) { @@ -66,6 +137,16 @@ function tablesort_get_querystring() { return $query_string; } +/** + * Determine the current sort criterion. + * + * @param $headers + * An array of column headers in the format described in theme_table(). + * @return + * An associative array describing the criterion, containing the keys: + * - "name": The localized title of the table column. + * - "sql": The name of the database field to sort on. + */ function tablesort_get_order($headers) { $order = $_GET['order']; foreach ($headers as $header) { @@ -93,14 +174,22 @@ function tablesort_get_order($headers) { } } +/** + * Determine the current sort direction. + * + * @param $headers + * An array of column headers in the format described in theme_table(). + * @return + * The current sort direction ("asc" or "desc"). + */ function tablesort_get_sort($headers) { if ($_GET['sort']) { return ($_GET['sort'] == 'desc') ? 'desc' : 'asc'; } - // user has not specified a sort. check module for default and if none, use 'asc' + // User has not specified a sort. Use default if specified; otherwise use "asc". else { foreach ($headers as $header) { - if (is_array($header) && isset($header['sort'])) { + if (is_array($header) && array_key_exists('sort', $header)) { return $header['sort']; } } Index: includes/theme.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/theme.inc,v retrieving revision 1.202 diff -u -F^function -r1.202 theme.inc --- includes/theme.inc 8 Jul 2004 16:08:21 -0000 1.202 +++ includes/theme.inc 21 Jul 2004 15:42:56 -0000 @@ -3,8 +3,7 @@ /** * @file - * - * Theme System - controls the output of Drupal. + * The theme system, which controls the output of Drupal. * * The theme system allows for nearly all output of the Drupal system to be * customized by user themes. @@ -21,32 +20,26 @@ * @return a string containing the help output. */ function theme_help($section) { - $output = ''; - switch ($section) { case 'admin/themes#description': - $output = t("The base theme"); - break; + return t('The base theme'); } - return $output; } /** * Initialize the theme system by loading the theme. * - * @return the name of the currently selected theme. + * @return + * The name of the currently selected theme. */ function init_theme() { global $user; $themes = list_themes(); - /* - ** Only select the user selected theme if it is available in the - ** list of enabled themes. - */ - - $theme = $user->theme && $themes[$user->theme] ? $user->theme : variable_get("theme_default", 0); + // Only select the user selected theme if it is available in the + // list of enabled themes. + $theme = $user->theme && $themes[$user->theme] ? $user->theme : variable_get('theme_default', 0); include_once($themes[$theme]->filename); @@ -57,10 +50,11 @@ function init_theme() { * Provides a list of currently available themes. * * @param $refresh - * - * @return an array of the currently available themes. + * Whether to reload the list of themes from the database. + * @return + * An array of the currently available themes. */ -function list_themes($refresh = 0) { +function list_themes($refresh = FALSE) { static $list; if ($refresh) { @@ -81,14 +75,22 @@ function list_themes($refresh = 0) { } /** - * External interface of the theme system to all other modules, and core files. + * Generate the themed representation of a Drupal object. * * All requests for themed functions must go through this function. It examines * the request and routes it to the appropriate theme function. If the current * theme does not implement the requested function, then the base theme function - * is called. Example: @verbatim $header_text = theme("header"); @endverbatim + * is called. * - * @return themed output. + * For example, to retrieve the HTML that is output by theme_page($output), a + * module should call theme('page', $output). + * + * @param $function + * The name of the theme function to call. + * @param ... + * Additional arguments to pass along to the theme function. + * @return + * An HTML string that generates the themed output. */ function theme() { global $theme; @@ -96,18 +98,16 @@ function theme() { $args = func_get_args(); $function = array_shift($args); - if (($theme != '') && (function_exists($theme ."_". $function))) { - return call_user_func_array($theme ."_". $function, $args); + if (($theme != '') && (function_exists($theme .'_'. $function))) { + return call_user_func_array($theme .'_'. $function, $args); } - elseif (function_exists("theme_". $function)){ - return call_user_func_array("theme_". $function, $args); + elseif (function_exists('theme_'. $function)){ + return call_user_func_array('theme_'. $function, $args); } } /** - * Returns the path to the currently selected theme. - * - * @return the path to the the currently selected theme. + * Return the path to the currently selected theme. */ function path_to_theme() { global $theme; @@ -121,22 +121,26 @@ function path_to_theme() { * @defgroup themeable Themeable functions * @{ * - * Themeable functions - functions that can be styled differently in themes. + * All functions that produce HTML for display should be themeable. This means + * that they should be named with the theme_ prefix, and invoked using theme() + * rather than being called directly. This allows themes to override the display + * of any Drupal object. * - * @see theme * @see theme.inc */ /** - * Returns an entire Drupal page displaying the supplied content. + * Return an entire Drupal page displaying the supplied content. * - * @param $content a string containing the content to display - * @param $title (optional) page title (\\) - * @param $breadcrumb (optional) page breadcrumb - * - * @see drupal_breadcrumb - * - * @return a string containing the @a page output. + * @param $content + * A string to display in the main content area of the page. + * @param $title + * The title of the page, if different from that provided by the menu system. + * @param $breadcrumb + * The breadcrumb trail for the page, if different from that provided by the + * menu system. Use menu_set_location() instead, if possible. + * @return + * A string containing the entire HTML page. */ function theme_page($content, $title = NULL, $breadcrumb = NULL) { if (isset($title)) { @@ -148,28 +152,28 @@ function theme_page($content, $title = N } $output = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n"; - $output .= "<html xmlns=\"http://www.w3.org/1999/xhtml\">"; - $output .= "<head>"; - $output .= " <title>". (drupal_get_title() ? drupal_get_title() : variable_get('site_name', "drupal")) .""; + $output .= ''; + $output .= ''; + $output .= ' '. (drupal_get_title() ? drupal_get_title() : variable_get('site_name', 'drupal')) .''; $output .= drupal_get_html_head(); - $output .= " "; - $output .= " "; - $output .= "
"; - - $output .= theme("box", t("Navigation"), @implode("
", link_page())); - $output .= theme("blocks", "all"); - $output .= "		"; + $output .= ' '; + $output .= ' '; + $output .= '
'; + + $output .= theme('box', t('Navigation'), @implode('
', link_page())); + $output .= theme('blocks', 'all'); + $output .= '		'; - $output .= theme("breadcrumb", drupal_get_breadcrumb()); - $output .= "

" . drupal_get_title() . "

"; + $output .= theme('breadcrumb', drupal_get_breadcrumb()); + $output .= '

' . drupal_get_title() . '

'; if ($tabs = theme('menu_local_tasks')) { $output .= $tabs; } if ($help = menu_get_active_help()) { - $output .= "$help
"; + $output .= ''. $help .'
'; } $output .= theme_status_messages(); @@ -178,9 +182,9 @@ function theme_page($content, $title = N $output .= $content; $output .= "\n\n"; - $output .= "
"; + $output .= '
'; $output .= theme_closure(); - $output .= ""; + $output .= ''; return $output; } @@ -189,7 +193,8 @@ function theme_page($content, $title = N * Returns themed set of status and/or error messages. The messages are grouped * by type. * - * @return a string containing the messages. + * @return + * A string containing the messages. */ function theme_status_messages() { if ($data = drupal_get_messages()) { @@ -199,7 +204,7 @@ function theme_status_messages() { if (count($messages) > 1) { $output .= " \n"; } @@ -213,94 +218,97 @@ function theme_status_messages() { } } - /** - * Returns themed set of links. - * - * @param $links an array of @a links to be themed. - * @param $delimiter (optional) @a delimiter used to separate the links. + * Return a themed set of links. * - * @return a string containing the @a links output. + * @param $links + * An array of links to be themed. + * @param $delimiter + * A string used to separate the links. + * @return + * A string containing the themed links. */ -function theme_links($links, $delimiter = " | ") { +function theme_links($links, $delimiter = ' | ') { return implode($delimiter, $links); } /** - * Returns themed image. + * Return a themed image. * - * @param $name the @a name of the image file. - * - * @return a string containing the @a image output. + * @param $name + * The name of the image file. + * @return + * The pathname of the themed image. */ function theme_image($name) { - return "misc/$name"; + return 'misc/'. $name; } /** - * Returns a themed breadcrumb menu. - * - * @param $breadcrumb an array containing the breadcrumb links. + * Return a themed breadcrumb trail. * - * @return a string containing the @a breadcrumb output. + * @param $breadcrumb + * An array containing the breadcrumb links. + * @return a string containing the breadcrumb output. */ function theme_breadcrumb($breadcrumb) { - return "
". implode($breadcrumb, ' » ') ."
"; + return '
'. implode($breadcrumb, ' » ') .'
'; } /** - * Returns themed node. - * - * The passed $node object provides a all relevant information for displaying a - * node: - * @li @c $node->nid - * @li @c $node->type i.e. story, blog, forum. - * @li @c $node->title - * @li @c $node->created a unix timestamp. - * @li @c $node->teaser - * @li @c $node->body - * @li @c $node->changed a unix timestamp. - * @li @c $node->uid the id of the poster. - * @li @c $node->username the username of the poster. - * - * @param $node the @a node to be themed. - * @param $main Display teaser only, as on main page? - * @param $page Display node as standalone page (no title)? + * Return a themed node. * - * @return a string containing the @a node output. - */ -function theme_node($node, $main = 0, $page = 0) { - if (module_exist("taxonomy")) { - $terms = taxonomy_link("taxonomy terms", $node); + * @param $node + * An object providing all relevant information for displaying a node: + * - $node->nid: The ID of the node. + * - $node->type: The content type (story, blog, forum...). + * - $node->title: The title of the node. + * - $node->created: The creation date, as a UNIX timestamp. + * - $node->teaser: A shortened version of the node body. + * - $node->body: The entire node contents. + * - $node->changed: The last modification date, as a UNIX timestamp. + * - $node->uid: The ID of the author. + * - $node->username: The username of the author. + * @param $teaser + * Whether to display the teaser only, as on the main page. + * @param $page + * Whether to display the node as a standalone page. If TRUE, do not display + * the title because it will be provided by the menu system. + * @return + * A string containing the node output. + */ +function theme_node($node, $teaser = FALSE, $page = FALSE) { + if (module_exist('taxonomy')) { + $terms = taxonomy_link('taxonomy terms', $node); } if ($page == 0) { - $output = "

$node->title

by ". format_name($node); + $output = '

'. $node->title .'

by '. format_name($node); } else { - $output = "by ". format_name($node); + $output = 'by '. format_name($node); } if (count($terms)) { - $output .= " (". theme('links', $terms) .")
"; + $output .= ' ('. theme('links', $terms) .')
'; } - if ($main && $node->teaser) { + if ($teaser && $node->teaser) { $output .= $node->teaser; } else { $output .= $node->body; } - if ($links = link_node($node, $main)) { - $output .= "
". theme('links', $links) ."
"; + if ($links = link_node($node, $teaser)) { + $output .= '
'. theme('links', $links) .'
'; } return $output; } /** - * Returns themed form element. + * Return a themed form element. * * @param $title the form element's title * @param $value the form element's data @@ -338,36 +346,44 @@ function theme_form_element($title, $val /** - * Returns themed sub menu, typically displayed under the tabs. + * Return a themed submenu, typically displayed under the tabs. * - * @param $menus an associative array of links. + * @param $links + * An array of links. */ - function theme_submenu($links) { - return "
". implode(' | ', $links) ."
"; + return '
'. implode(' | ', $links) .'
'; } /** - * Returns themed table. + * Return a themed table. * - * @param $header array of table header strings - * @param $rows array of arrays containing the table cells - * @param $attributes attribute array for the table tag - * - * @return a string representing the table. + * @param $header + * An array containing the table headers. Each element of the array can be + * either a localized string or an associative array with the following keys: + * - "data": The localized title of the table column. + * - "field": The database field represented in the table column (required if + * user is to be able to sort on this column). + * - "sort": A default sort order for this column ("asc" or "desc"). + * - Any HTML attributes, such as "colspan", to apply to the column header cell. + * @param $rows + * An array of arrays containing the table cells. Each cell can be either a + * string or and associative array with the following keys: + * - "data": The string to display in the table cell. + * - Any HTML attributes, such as "colspan", to apply to the table cell. + * @param $attributes + * An array of HTML attributes to apply to the table tag. + * @return + * An HTML string representing the table. */ - function theme_table($header, $rows, $attributes = NULL) { - $output = "\n"; - - /* - ** Emit the table header: - */ + $output = '
\n"; + // Format the table header: if (is_array($header)) { $ts = tablesort_init($header); - $output .= " "; + $output .= ' '; foreach ($header as $cell) { $cell = tablesort_header($cell, $header, $ts); $output .= _theme_table_cell($cell, 1); @@ -375,27 +391,23 @@ function theme_table($header, $rows, $at $output .= " \n"; } - /* - ** Emit the table rows: - */ - + // Format the table rows: if (is_array($rows)) { - $i = 0; foreach ($rows as $number => $row) { if ($number % 2 == 1) { - $output .= " "; + $output .= ' '; } else { - $output .= " "; + $output .= ' '; } + $i = 0; foreach ($row as $cell) { $cell = tablesort_cell($cell, $header, $ts, $i); $output .= _theme_table_cell($cell, 0); $i++; } $output .= " \n"; - $i = 0; } } @@ -404,32 +416,36 @@ function theme_table($header, $rows, $at } /** - * Returns themed box. + * Return a themed box. * - * @param $title the @a subject of the box. - * @param $content the @a content of the box. - * @param $region the @a region of the box. - * - * @return a string containing the @a box output. + * @param $title + * The subject of the box. + * @param $content + * The content of the box. + * @param $region + * The region in which the box is displayed. + * @return + * A string containing the box output. */ function theme_box($title, $content, $region = 'main') { - $output = "

$title

$content
"; + $output = '

'. $title .'

'. $content .'
'; return $output; } /** - * Returns a themed block. + * Return a themed block. * * You can style your blocks by defining .block (all blocks), * .block-module (all blocks of module module), and * \#block-module-delta (specific block of module module * with delta delta) in your theme's CSS. * - * @param $block object "indexed with" fields from database table 'blocks' + * @param $block + * An object populated with fields from the "blocks" database table * ($block->module, $block->delta, $block->region, ...) and fields returned by - * module_block("view") ($block->subject, $block->content, ...). - * - * @return a string containing the @a box output. + * module_block('view') ($block->subject, $block->content, ...). + * @return + * A string containing the block output. */ function theme_block($block) { $output = "
module\" id=\"block-$block->module-$block->delta\">\n"; @@ -440,68 +456,72 @@ function theme_block($block) { } /** - * Returns themed marker, useful for marking new comments or required form + * Return a themed marker, useful for marking new comments or required form * elements. * - * @return a string containing the @a mark output. + * @return + * A string containing the marker. */ function theme_mark() { return '*'; } /** - * Returns themed list of items. + * Return a themed list of items. * - * @param $items (optional) an array of the items to be displayed in a list. - * @param $title (optional) the title of the list. - * - * @return a string containing the @a list output. + * @param $items + * An array of items to be displayed in the list. + * @param $title + * The title of the list. + * @return + * A string containing the list output. */ function theme_item_list($items = array(), $title = NULL) { - $output = "
"; + $output = '
'; if (isset($title)) { - $output .= "

$title

"; + $output .= '

'. $title .'

'; } if (isset($items)) { - $output .= "
    "; + $output .= '
      '; foreach ($items as $item) { - $output .= "
    • $item
      • "; + $output .= '
    • '. $item .'
      • '; } - $output .= "
    "; + $output .= '
'; } - $output .= "
"; + $output .= '
'; return $output; } /** - * Returns themed error message. + * Return a themed error message. * REMOVE: this function is deprecated an no longer used in core. * - * @param $message the error message to be themed. + * @param $message + * The error message to be themed. * - * @return a string containing the @a error output. + * @return + * A string containing the error output. */ function theme_error($message) { - return "
$message
"; + return '
'. $message .'
'; } /** - * Returns code that emits an XML-icon. - * - * @return a string containing the @a output. + * Return code that emits an XML icon. */ function theme_xml_icon($url) { - return "
\"".
"; + return '
'. t('XML feed') .'
'; } /** - * Execute hook _footer() which is run at the end of the page right before the - * \ tag. + * Execute hook_footer() which is run at the end of the page right before the + * close of the body tag. * * @param $main (optional) * - * @return a string containing the @a closure output. + * @return + * A string containing the results of the hook_footer() calls. */ function theme_closure($main = 0) { $footer = module_invoke_all('footer', $main); @@ -509,12 +529,13 @@ function theme_closure($main = 0) { } /** - * Call _onload hook in all modules to enable modules to insert javascript that + * Call hook_onload() in all modules to enable modules to insert JavaScript that * will get run once the page has been loaded by the browser. * - * @param $theme_onloads (optional) addition onload directives. - * - * @return a string containing the @a onload output. + * @param $theme_onloads + * Additional onload directives. + * @return + * A string containing the onload attributes. */ function theme_onload_attribute($theme_onloads = array()) { if (!is_array($theme_onloads)) { @@ -522,19 +543,20 @@ function theme_onload_attribute($theme_o } // Merge theme onloads (javascript rollovers, image preloads, etc.) // with module onloads (htmlarea, etc.) - $onloads = array_merge(module_invoke_all("onload"), $theme_onloads); + $onloads = array_merge(module_invoke_all('onload'), $theme_onloads); if (count($onloads)) { - return " onload=\"" . implode("; ", $onloads) . "\""; + return ' onload="' . implode('; ', $onloads) . '"'; } return ''; } /** - * Returns themed blocks available for current $user at $region. - * - * @param $region main|left|right + * Return a set of blocks available for the current user. * - * @return a string containing the @a blocks output. + * @param $region + * Which set of blocks to retrieve. + * @return + * A string containing the themed blocks for this region. */ function theme_blocks($region) { $output = ''; @@ -547,7 +569,9 @@ function theme_blocks($region) { } return $output; } -/* @} */ +/** + * @} end of defgroup themeable + */ function _theme_table_cell($cell, $header = 0) { $attributes = '';