diff options
Diffstat (limited to 'includes/theme.inc')
| -rw-r--r-- | includes/theme.inc | 376 |
1 files changed, 200 insertions, 176 deletions
diff --git a/includes/theme.inc b/includes/theme.inc index efc35721d..c43b45df6 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -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. + * + * For example, to retrieve the HTML that is output by theme_page($output), a + * module should call theme('page', $output). * - * @return themed 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. - * - * @param $content a string containing the content to display - * @param $title (optional) page title (\<head>\<title>) - * @param $breadcrumb (optional) page breadcrumb - * - * @see drupal_breadcrumb - * - * @return a string containing the @a page output. + * Return an entire Drupal page displaying the supplied content. + * + * @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 = NULL, $breadcrumb = NULL) { } $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")) ."</title>"; + $output .= '<html xmlns="http://www.w3.org/1999/xhtml">'; + $output .= '<head>'; + $output .= ' <title>'. (drupal_get_title() ? drupal_get_title() : variable_get('site_name', 'drupal')) .'</title>'; $output .= drupal_get_html_head(); - $output .= " </head>"; - $output .= " <body style=\"background-color: #fff; color: #000;\"". theme("onload_attribute"). "\">"; - $output .= "<table border=\"0\" cellspacing=\"4\" cellpadding=\"4\"><tr><td style=\"vertical-align: top; width: 170px;\">"; + $output .= ' </head>'; + $output .= ' <body style="background-color: #fff; color: #000;"'. theme('onload_attribute'). '">'; + $output .= '<table border="0" cellspacing="4" cellpadding="4"><tr><td style="vertical-align: top; width: 170px;">'; - $output .= theme("box", t("Navigation"), @implode("<br />", link_page())); - $output .= theme("blocks", "all"); - $output .= "</td><td style=\"vertical-align: top;\">"; + $output .= theme('box', t('Navigation'), @implode('<br />', link_page())); + $output .= theme('blocks', 'all'); + $output .= '</td><td style="vertical-align: top;">'; - $output .= theme("breadcrumb", drupal_get_breadcrumb()); - $output .= "<h1>" . drupal_get_title() . "</h1>"; + $output .= theme('breadcrumb', drupal_get_breadcrumb()); + $output .= '<h1>' . drupal_get_title() . '</h1>'; if ($tabs = theme('menu_local_tasks')) { $output .= $tabs; } if ($help = menu_get_active_help()) { - $output .= "<small>$help</small><hr />"; + $output .= '<small>'. $help .'</small><hr />'; } $output .= theme_status_messages(); @@ -178,9 +182,9 @@ function theme_page($content, $title = NULL, $breadcrumb = NULL) { $output .= $content; $output .= "\n<!-- end content -->\n"; - $output .= "</td></tr></table>"; + $output .= '</td></tr></table>'; $output .= theme_closure(); - $output .= "</body></html>"; + $output .= '</body></html>'; return $output; } @@ -189,7 +193,8 @@ function theme_page($content, $title = NULL, $breadcrumb = NULL) { * 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 .= " <ul>\n"; foreach($messages as $message) { - $output .= " <li>". ucfirst($message) ."</li>\n"; + $output .= ' <li>'. ucfirst($message) ."</li>\n"; } $output .= " </ul>\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 string containing the @a links output. + * Return a themed set of links. + * + * @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. - * - * @param $name the @a name of the image file. + * Return a themed image. * - * @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. + * Return a themed breadcrumb trail. * - * @param $breadcrumb an array containing the breadcrumb links. - * - * @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 "<div class=\"breadcrumb\">". implode($breadcrumb, ' » ') ."</div>"; + return '<div class="breadcrumb">'. implode($breadcrumb, ' » ') .'</div>'; } /** - * 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 string containing the @a node output. + * Return a themed 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, $main = 0, $page = 0) { - if (module_exist("taxonomy")) { - $terms = taxonomy_link("taxonomy terms", $node); +function theme_node($node, $teaser = FALSE, $page = FALSE) { + if (module_exist('taxonomy')) { + $terms = taxonomy_link('taxonomy terms', $node); } if ($page == 0) { - $output = "<h2 class=\"title\">$node->title</h2> by ". format_name($node); + $output = '<h2 class="title">'. $node->title .'</h2> by '. format_name($node); } else { - $output = "by ". format_name($node); + $output = 'by '. format_name($node); } if (count($terms)) { - $output .= " <small>(". theme('links', $terms) .")</small><br />"; + $output .= ' <small>('. theme('links', $terms) .')</small><br />'; } - if ($main && $node->teaser) { + if ($teaser && $node->teaser) { $output .= $node->teaser; } else { $output .= $node->body; } - if ($links = link_node($node, $main)) { - $output .= "<div class=\"links\">". theme('links', $links) ."</div>"; + if ($links = link_node($node, $teaser)) { + $output .= '<div class="links">'. theme('links', $links) .'</div>'; } 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, $value, $description = NULL, $id = NULL, $re /** - * 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 "<div class=\"submenu\">". implode(' | ', $links) ."</div>"; + return '<div class="submenu">'. implode(' | ', $links) .'</div>'; } /** - * Returns 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. + * Return a themed 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 = "<table ". drupal_attributes($attributes) .">\n"; - - /* - ** Emit the table header: - */ + $output = '<table '. drupal_attributes($attributes) .">\n"; + // Format the table header: if (is_array($header)) { $ts = tablesort_init($header); - $output .= " <tr>"; + $output .= ' <tr>'; 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, $attributes = NULL) { $output .= " </tr>\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 .= " <tr class=\"light\">"; + $output .= ' <tr class="light">'; } else { - $output .= " <tr class=\"dark\">"; + $output .= ' <tr class="dark">'; } + $i = 0; foreach ($row as $cell) { $cell = tablesort_cell($cell, $header, $ts, $i); $output .= _theme_table_cell($cell, 0); $i++; } $output .= " </tr>\n"; - $i = 0; } } @@ -404,32 +416,36 @@ function theme_table($header, $rows, $attributes = NULL) { } /** - * Returns 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. + * Return a themed box. + * + * @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 = "<h2 class=\"title\">$title</h2><div>$content</div>"; + $output = '<h2 class="title">'. $title .'</h2><div>'. $content .'</div>'; return $output; } /** - * Returns a themed block. + * Return a themed block. * * You can style your blocks by defining .block (all blocks), * .block-<i>module</i> (all blocks of module <i>module</i>), and * \#block-<i>module</i>-<i>delta</i> (specific block of module <i>module</i> * with delta <i>delta</i>) 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 - * <i>module</i>_block("view") ($block->subject, $block->content, ...). - * - * @return a string containing the @a box output. + * <i>module</i>_block('view') ($block->subject, $block->content, ...). + * @return + * A string containing the block output. */ function theme_block($block) { $output = "<div class=\"block block-$block->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 '<span class="marker">*</span>'; } /** - * Returns 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. + * Return a themed list of items. + * + * @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 = "<div class=\"item-list\">"; + $output = '<div class="item-list">'; if (isset($title)) { - $output .= "<h3>$title</h3>"; + $output .= '<h3>'. $title .'</h3>'; } if (isset($items)) { - $output .= "<ul>"; + $output .= '<ul>'; foreach ($items as $item) { - $output .= "<li>$item</li>"; + $output .= '<li>'. $item .'</li>'; } - $output .= "</ul>"; + $output .= '</ul>'; } - $output .= "</div>"; + $output .= '</div>'; 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 "<div class=\"error\">$message</div>"; + return '<div class="error">'. $message .'</div>'; } /** - * 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 "<div class=\"xml-icon\"><a href=\"$url\"><img src=\"misc/xml.png\" width=\"36\" height=\"14\" alt=\"". t('XML feed') ."\" /></a></div>"; + return '<div class="xml-icon"><a href="'. $url .'"><img src="misc/xml.png" width="36" height="14" alt="'. t('XML feed') .'" /></a></div>'; } /** - * Execute hook _footer() which is run at the end of the page right before the - * \</body> 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_onloads = array()) { } // 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 = ''; |