diff options
47 files changed, 551 insertions, 493 deletions
diff --git a/includes/form.inc b/includes/form.inc index 93d0304b6..fcadc3c36 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -1929,7 +1929,11 @@ function _form_options_flatten($array) { } /** - * Theme select form element. + * Returns HTML for a select form element. + * + * It is possible to group options together; to do this, change the format of + * $options to an associative array in which the keys are group labels, and the + * values are associative arrays in the normal $options format. * * @param $variables * An associative array containing: @@ -1937,14 +1941,7 @@ function _form_options_flatten($array) { * Properties used: #title, #value, #options, #description, #extra, * #multiple, #required, #name, #attributes, #size. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable - * - * It is possible to group options together; to do this, change the format of - * $options to an associative array in which the keys are group labels, and the - * values are associative arrays in the normal $options format. */ function theme_select($variables) { $element = $variables['element']; @@ -2049,7 +2046,7 @@ function form_get_options($element, $key) { } /** - * Theme a fieldset form element. + * Returns HTML for a fieldset form element and its children. * * @param $variables * An associative array containing: @@ -2057,9 +2054,6 @@ function form_get_options($element, $key) { * Properties used: #attributes, #children, #collapsed, #collapsible, * #description, #id, #title, #value. * - * @return - * A themed HTML string representing the group of items. - * * @ingroup themeable */ function theme_fieldset($variables) { @@ -2084,7 +2078,7 @@ function theme_fieldset($variables) { } /** - * Theme a radio button form element. + * Returns HTML for a radio button form element. * * @param $variables * An associative array containing: @@ -2092,9 +2086,6 @@ function theme_fieldset($variables) { * Properties used: #required, #return_value, #value, #attributes, #title, * #description * - * @return - * A themed HTML string representing the form item group. - * * @ingroup themeable */ function theme_radio($variables) { @@ -2111,7 +2102,7 @@ function theme_radio($variables) { } /** - * Theme a set of radio button form elements. + * Returns HTML for a set of radio button form elements. * * @param $variables * An associative array containing: @@ -2119,9 +2110,6 @@ function theme_radio($variables) { * Properties used: #title, #value, #options, #description, #required, * #attributes, #children. * - * @return - * A themed HTML string representing the radio button set. - * * @ingroup themeable */ function theme_radios($variables) { @@ -2191,7 +2179,7 @@ function password_confirm_validate($element, &$element_state) { } /** - * Theme a date selection form element. + * Returns HTML for a date selection form element. * * @param $variables * An associative array containing: @@ -2199,9 +2187,6 @@ function password_confirm_validate($element, &$element_state) { * Properties used: #title, #value, #options, #description, #required, * #attributes. * - * @return - * A themed HTML string representing the date selection boxes. - * * @ingroup themeable */ function theme_date($variables) { @@ -2330,7 +2315,7 @@ function form_process_radios($element) { } /** - * Theme a checkbox form element. + * Returns HTML for a checkbox form element. * * @param $variables * An associative array containing: @@ -2338,9 +2323,6 @@ function form_process_radios($element) { * Properties used: #title, #value, #return_value, #description, #required, * #attributes. * - * @return - * A themed HTML string representing the checkbox. - * * @ingroup themeable */ function theme_checkbox($variables) { @@ -2362,16 +2344,13 @@ function theme_checkbox($variables) { } /** - * Theme a set of checkbox form elements. + * Returns HTML for a set of checkbox form elements. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #children, #attributes. * - * @return - * A themed HTML string representing the checkbox set. - * * @ingroup themeable */ function theme_checkboxes($variables) { @@ -2456,14 +2435,12 @@ function form_process_container($element, &$form_state) { } /** - * Adds a container for grouped items. + * Returns HTML for a container for grouped form items. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #id, #attributes, #children. - * @return - * A themed HTML string representing the form element. * * @ingroup themeable */ @@ -2478,16 +2455,9 @@ function theme_container($variables) { } /** - * Formats a table with radio buttons or checkboxes. + * Returns HTML for a table with radio buttons or checkboxes. * - * @param $variables - * An associative array containing: - * - element: An associative array containing the properties and children of - * the tableselect element. Properties used: #header, #options, #empty, - * and #js_select. The #options property is an array of selection options; - * each array element of #options is an array of properties. These - * properties can include #attributes, which is added to the - * table row's HTML attributes (see theme_table()). Example: + * An example of per-row options: * @code * $options = array(); * $options[0]['title'] = "A red row" @@ -2502,8 +2472,14 @@ function theme_container($variables) { * ); * @endcode * - * @return - * A themed HTML string representing the table. + * @param $variables + * An associative array containing: + * - element: An associative array containing the properties and children of + * the tableselect element. Properties used: #header, #options, #empty, + * and #js_select. The #options property is an array of selection options; + * each array element of #options is an array of properties. These + * properties can include #attributes, which is added to the + * table row's HTML attributes; see theme_table(). * * @ingroup themeable */ @@ -2747,16 +2723,13 @@ function form_process_vertical_tabs($element, &$form_state) { } /** - * Makes the element's children fieldsets be vertical tabs. + * Returns HTML for an element's children fieldsets as vertical tabs. * * @param $variables * An associative array containing: * - element: An associative array containing the properties and children of the * fieldset. Properties used: #children. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable */ function theme_vertical_tabs($variables) { @@ -2770,16 +2743,13 @@ function theme_vertical_tabs($variables) { } /** - * Theme a submit button form element. + * Returns HTML for a submit button form element. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #attributes, #button_type, #name, #value. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable */ function theme_submit($variables) { @@ -2788,16 +2758,13 @@ function theme_submit($variables) { } /** - * Theme a button form element. + * Returns HTML for a button form element. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #attributes, #button_type, #name, #value. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable */ function theme_button($variables) { @@ -2808,15 +2775,13 @@ function theme_button($variables) { } /** - * Theme a image button form element. + * Returns HTML for an image button form element. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #attributes, #button_type, #name, #value, #title, #src. * - * @return - * A themed HTML string representing the form element. * @ingroup themeable */ function theme_image_button($variables) { @@ -2833,16 +2798,13 @@ function theme_image_button($variables) { } /** - * Theme a hidden form element. + * Returns HTML for a hidden form element. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #name, #value, #attributes. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable */ function theme_hidden($variables) { @@ -2851,7 +2813,7 @@ function theme_hidden($variables) { } /** - * Theme a textfield form element. + * Returns HTML for a textfield form element. * * @param $variables * An associative array containing: @@ -2859,9 +2821,6 @@ function theme_hidden($variables) { * Properties used: #title, #value, #description, #size, #maxlength, * #required, #attributes, #autocomplete_path. * - * @return - * A themed HTML string representing the textfield. - * * @ingroup themeable */ function theme_textfield($variables) { @@ -2885,16 +2844,13 @@ function theme_textfield($variables) { } /** - * Theme a form. + * Returns HTML for a form. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #action, #method, #attributes, #children * - * @return - * A themed HTML string representing the form. - * * @ingroup themeable */ function theme_form($variables) { @@ -2905,7 +2861,7 @@ function theme_form($variables) { } /** - * Theme a textarea form element. + * Returns HTML for a textarea form element. * * @param $variables * An associative array containing: @@ -2913,9 +2869,6 @@ function theme_form($variables) { * Properties used: #title, #value, #description, #rows, #cols, #required, * #attributes * - * @return - * A themed HTML string representing the textarea. - * * @ingroup themeable */ function theme_textarea($variables) { @@ -2941,7 +2894,7 @@ function theme_textarea($variables) { } /** - * Theme a password form element. + * Returns HTML for a password form element. * * @param $variables * An associative array containing: @@ -2949,9 +2902,6 @@ function theme_textarea($variables) { * Properties used: #title, #value, #description, #size, #maxlength, * #required, #attributes. * - * @return - * A themed HTML string representing the form element. - * * @ingroup themeable */ function theme_password($variables) { @@ -2979,7 +2929,10 @@ function form_process_weight($element) { } /** - * Theme a file upload form element. + * Returns HTML for a file upload form element. + * + * For assistance with handling the uploaded file correctly, see the API + * provided by file.inc. * * @param $variables * An associative array containing: @@ -2987,13 +2940,7 @@ function form_process_weight($element) { * Properties used: #title, #name, #size, #description, #required, * #attributes. * - * @return - * A themed HTML string representing the field. - * * @ingroup themeable - * - * For assistance with handling the uploaded file correctly, see the API - * provided by file.inc. */ function theme_file($variables) { $element = $variables['element']; @@ -3002,7 +2949,7 @@ function theme_file($variables) { } /** - * Theme a form element. + * Returns HTML for a form element. * * Each form element is wrapped in a DIV with #type and #name classes. In * addition to the element itself, the div contains a label before or after @@ -3039,9 +2986,6 @@ function theme_file($variables) { * Properties used: #title, #title_display, #description, #id, #required, * #children, #type, #name. * - * @return - * A string representing the form element. - * * @ingroup themeable */ function theme_form_element($variables) { @@ -3102,13 +3046,11 @@ function theme_form_element($variables) { } /** - * Theme the marker for required form elements. + * Returns HTML for a marker for required form elements. * * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. - * @return - * A string representing the marker to identify required form elements. * * @ingroup themeable */ @@ -3123,7 +3065,7 @@ function theme_form_required_marker($variables) { } /** - * Theme a form element label and required marker. + * Returns HTML for a form element label and required marker. * * Form element labels include the #title and a #required marker. The label is * associated with the element itself by the element #id. Labels may appear @@ -3141,8 +3083,6 @@ function theme_form_required_marker($variables) { * An associative array containing: * - element: An associative array containing the properties of the element. * Properties used: #required, #title, #id, #value, #description. - * @return - * A string representing the form element label. * * @ingroup themeable */ diff --git a/includes/menu.inc b/includes/menu.inc index 048980d03..4b5ca3aed 100644 --- a/includes/menu.inc +++ b/includes/menu.inc @@ -1372,24 +1372,20 @@ function _menu_tree_data(&$links, $parents, $depth) { } /** - * Preprocess the rendered tree for theme_menu_tree. - * - * @ingroup themeable + * Preprocesses the rendered tree for theme_menu_tree(). */ function template_preprocess_menu_tree(&$variables) { $variables['tree'] = $variables['tree']['#children']; } /** - * Theme wrapper for the HTML output for a menu sub-tree. + * Returns HTML for a wrapper for a menu sub-tree. * * @param $variables * An associative array containing: - * - tree: @todo: document - * - * @return - * A themed HTML string. + * - tree: An HTML string containing the tree's items. * + * @see template_preprocess_menu_tree() * @ingroup themeable */ function theme_menu_tree($variables) { @@ -1397,15 +1393,12 @@ function theme_menu_tree($variables) { } /** - * Generate the HTML output for a menu link and submenu. + * Returns HTML for a menu link and submenu. * * @param $variables * An associative array containing: * - element: Structured array data for a menu link. * - * @return - * A themed HTML string. - * * @ingroup themeable */ function theme_menu_link(array $variables) { @@ -1420,13 +1413,14 @@ function theme_menu_link(array $variables) { } /** - * Generate the HTML output for a single local task link. + * Returns HTML for a single local task link. * * @param $variables * An associative array containing: - * - #link: A menu link array with 'title', 'href', and 'localized_options' - * keys. - * - #active: A boolean indicating whether the local task is active. + * - element: A render element containing: + * - #link: A menu link array with 'title', 'href', and 'localized_options' + * keys. + * - #active: A boolean indicating whether the local task is active. * * @ingroup themeable */ @@ -1451,12 +1445,13 @@ function theme_menu_local_task($variables) { } /** - * Generate the HTML output for a single local action link. + * Returns HTML for a single local action link. * * @param $variables * An associative array containing: - * - #link: A menu link array with 'title', 'href', and 'localized_options' - * keys. + * - element: A render element containing: + * - #link: A menu link array with 'title', 'href', and 'localized_options' + * keys. * * @ingroup themeable */ diff --git a/includes/pager.inc b/includes/pager.inc index 7430cfe8c..a33087c64 100644 --- a/includes/pager.inc +++ b/includes/pager.inc @@ -186,11 +186,11 @@ function pager_get_query_parameters() { } /** - * Format a query pager. + * Returns HTML for 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. - * Format a list of nearby pages with additional query results. + * retrieve a pager control so that users can view other results. Format a list + * of nearby pages with additional query results. * * @param $variables * An associative array containing: @@ -201,9 +201,6 @@ function pager_get_query_parameters() { * the pager links. * - quantity: The number of pages in the list. * - * @return - * An HTML string that generates the query pager. - * * @ingroup themeable */ function theme_pager($variables) { @@ -321,7 +318,7 @@ function theme_pager($variables) { */ /** - * Format a "first page" link. + * Returns HTML for the "first page" link in a query pager. * * @param $variables * An associative array containing: @@ -331,9 +328,6 @@ function theme_pager($variables) { * - parameters: 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. - * * @ingroup themeable */ function theme_pager_first($variables) { @@ -352,7 +346,7 @@ function theme_pager_first($variables) { } /** - * Format a "previous page" link. + * Returns HTML for the "previous page" link in a query pager. * * @param $variables * An associative array containing: @@ -363,9 +357,6 @@ function theme_pager_first($variables) { * - parameters: 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. - * * @ingroup themeable */ function theme_pager_previous($variables) { @@ -394,7 +385,7 @@ function theme_pager_previous($variables) { } /** - * Format a "next page" link. + * Returns HTML for the "next page" link in a query pager. * * @param $variables * An associative array containing: @@ -405,9 +396,6 @@ function theme_pager_previous($variables) { * - parameters: 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. - * * @ingroup themeable */ function theme_pager_next($variables) { @@ -435,7 +423,7 @@ function theme_pager_next($variables) { } /** - * Format a "last page" link. + * Returns HTML for the "last page" link in query pager. * * @param $variables * An associative array containing: @@ -445,9 +433,6 @@ function theme_pager_next($variables) { * - parameters: 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. - * * @ingroup themeable */ function theme_pager_last($variables) { @@ -467,7 +452,7 @@ function theme_pager_last($variables) { /** - * Format a link to a specific query result page. + * Returns HTML for a link to a specific query result page. * * @param $variables * An associative array containing: @@ -479,9 +464,6 @@ function theme_pager_last($variables) { * - attributes: An associative array of HTML attributes to apply to a pager * anchor tag. * - * @return - * An HTML string that generates the link. - * * @ingroup themeable */ function theme_pager_link($variables) { diff --git a/includes/theme.inc b/includes/theme.inc index 2e5c691bd..6bfb95c40 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -1329,8 +1329,7 @@ function theme_disable($theme_list) { */ /** - * Return a themed set of status and/or error messages. The messages are grouped - * by type. + * Returns HTML for status and/or error messages, grouped by type. * * An invisible heading identifies the messages for assistive technology. * Sighted users see a colored box. See http://www.w3.org/TR/WCAG-TECHS/H69.html @@ -1340,9 +1339,6 @@ function theme_disable($theme_list) { * An associative array containing: * - display: (optional) Set to 'status' or 'error' to display only messages * of that type. - * - * @return - * A string containing the messages. */ function theme_status_messages($variables) { $display = $variables['display']; @@ -1374,11 +1370,11 @@ function theme_status_messages($variables) { } /** - * Return a themed link. + * Returns HTML for a link. * * All Drupal code that outputs a link should call the l() function. That - * function performs some initial preprocessing, and then, if necessary, - * calls theme('link') for rendering the anchor tag. + * function performs some initial preprocessing, and then, if necessary, calls + * theme('link') for rendering the anchor tag. * * To optimize performance for sites that don't need custom theming of links, * the l() function includes an inline copy of this function, and uses that copy @@ -1386,11 +1382,8 @@ function theme_status_messages($variables) { * or process functions or override this theme implementation. * * @param $variables - * An associative array containing the keys 'text', 'path', and 'options'. - * See the l() function for information about these variables. - * - * @return - * An HTML string containing a link to the given path. + * An associative array containing the keys 'text', 'path', and 'options'. See + * the l() function for information about these variables. * * @see l() */ @@ -1399,28 +1392,29 @@ function theme_link($variables) { } /** - * Return a themed set of links. + * Returns HTML for a set of links. * * @param $variables * An associative array containing: * - links: A keyed array of links to be themed. The key for each link is used * as its css class. Each link should be itself an array, with the following * keys: - * - title: the link text - * - href: the link URL. If omitted, the 'title' is shown as a plain text - * item in the links list. - * - html: (optional) set this to TRUE if 'title' is HTML so it will be - * escaped. + * - title: the link text + * - href: the link URL. If omitted, the 'title' is shown as a plain text + * item in the links list. + * - html: (optional) set this to TRUE if 'title' is HTML so it will be + * escaped. * Array items are passed on to the l() function's $options parameter when * creating the link. * - attributes: A keyed array of attributes. * - heading: An optional keyed array or a string for a heading to precede the * links. When using an array the following keys can be used: - * - text: the heading text - * - level: the heading level (e.g. 'h2', 'h3') - * - class: (optional) an array of the CSS classes for the heading + * - text: the heading text + * - level: the heading level (e.g. 'h2', 'h3') + * - class: (optional) an array of the CSS classes for the heading * When using a string it will be used as the text of the heading and the * level will default to 'h2'. + * * Headings should be used on navigation menus and any list of links that * consistently appears on multiple pages. To make the heading invisible * use the 'element-invisible' CSS class. Do not use 'display:none', which @@ -1428,9 +1422,6 @@ function theme_link($variables) { * screen-reader and keyboard only users to navigate to or skip the links. * See http://juicystudio.com/article/screen-readers-display-none.php * and http://www.w3.org/TR/WCAG-TECHS/H42.html for more information. - * - * @return - * A string containing an unordered list of links. */ function theme_links($variables) { $links = $variables['links']; @@ -1509,7 +1500,7 @@ function theme_links($variables) { } /** - * Return a themed image. + * Returns HTML for an image. * * @param $variables * An associative array containing: @@ -1521,9 +1512,6 @@ function theme_links($variables) { * - attributes: Associative array of attributes to be placed in the img tag. * - getsize: If set to TRUE, the image's dimension are fetched and added as * width/height attributes. - * - * @return - * A string containing the image tag. */ function theme_image($variables) { $path = $variables['path']; @@ -1540,14 +1528,11 @@ function theme_image($variables) { } /** - * Return a themed breadcrumb trail. + * Returns HTML for a breadcrumb trail. * * @param $variables * An associative array containing: * - breadcrumb: An array containing the breadcrumb links. - * - * @return - * A string containing the breadcrumb output. */ function theme_breadcrumb($variables) { $breadcrumb = $variables['breadcrumb']; @@ -1563,7 +1548,7 @@ function theme_breadcrumb($variables) { } /** - * Return a themed table. + * Returns HTML for a table. * * @param $variables * An associative array containing: @@ -1634,9 +1619,6 @@ function theme_breadcrumb($variables) { * - sticky: Use a "sticky" table header. * - empty: The message to display in an extra row if table does not have any * rows. - * - * @return - * An HTML string representing the table. */ function theme_table($variables) { $header = $variables['header']; @@ -1763,7 +1745,10 @@ function theme_table($variables) { } /** - * Returns a header cell for tables that have a select all functionality. + * Returns attributes for a header cell of tables with select all functionality. + * + * @return + * An array of attributes. */ function theme_table_select_header_cell() { drupal_add_js('misc/tableselect.js'); @@ -1772,14 +1757,11 @@ function theme_table_select_header_cell() { } /** - * Return a themed sort icon. + * Returns HTML for a sort icon. * * @param $variables * An associative array containing: - * - style: Set to either asc or desc. This sets which icon to show. - * - * @return - * A themed sort icon. + * - style: Set to either 'asc' or 'desc', this determines which icon to show. */ function theme_tablesort_indicator($variables) { if ($variables['style'] == "asc") { @@ -1791,16 +1773,12 @@ function theme_tablesort_indicator($variables) { } /** - * Return a themed marker, useful for marking new or updated - * content. + * Returns HTML for a marker for new or updated content. * * @param $variables * An associative array containing: * - type: Number representing the marker type to display. See MARK_NEW, * MARK_UPDATED, MARK_READ. - * - * @return - * A string containing the marker. */ function theme_mark($variables) { $type = $variables['type']; @@ -1816,7 +1794,7 @@ function theme_mark($variables) { } /** - * Return a themed list of items. + * Returns HTML for a list or nested list of items. * * @param $variables * An associative array containing: @@ -1829,9 +1807,6 @@ function theme_mark($variables) { * - title: The title of the list. * - type: The type of list to return (e.g. "ul", "ol"). * - attributes: The attributes applied to the list element. - * - * @return - * A string containing the list output. */ function theme_item_list($variables) { $items = $variables['items']; @@ -1885,14 +1860,18 @@ function theme_item_list($variables) { } /** - * Returns code that emits the 'more help'-link. + * Returns HTML for a "more help" link. + * + * @param $variables + * An associative array containing: + * - url: The url for the link. */ function theme_more_help_link($variables) { return '<div class="more-help-link">' . t('<a href="@link">More help</a>', array('@link' => check_url($variables['url']))) . '</div>'; } /** - * Return code that emits an feed icon. + * Returns HTML for a feed icon. * * @param $variables * An associative array containing: @@ -1907,15 +1886,12 @@ function theme_feed_icon($variables) { } /** - * Generate the output for a generic HTML tag with attributes. - * - * This theme function should be used for tags appearing in the HTML HEAD of a - * document (specified via the #tag property in the passed $element): + * Returns HTML for a generic HTML tag with attributes. * * @param $variables * An associative array containing: * - element: An associative array describing the tag: - * - #tag: The tag name to output. Typical tags added to the HTML HEAD: + * - #tag: The tag name to output. Typical tags added to the HTML HEAD: * - meta: To provide meta information, such as a page refresh. * - link: To refer to stylesheets and other contextual information. * - script: To load JavaScript. @@ -1947,96 +1923,19 @@ function theme_html_tag($variables) { } /** - * Returns code that emits the 'more' link used on blocks. + * Returns HTML for a "more" link, like those used in blocks. * * @param $variables * An associative array containing: - * - url: The url of the main page - * - title: A descriptive verb for the link, like 'Read more' + * - url: The url of the main page. + * - title: A descriptive verb for the link, like 'Read more'. */ function theme_more_link($variables) { return '<div class="more-link">' . t('<a href="@link" title="@title">More</a>', array('@link' => check_url($variables['url']), '@title' => $variables['title'])) . '</div>'; } /** - * Preprocess variables for theme_username(). - * - * Modules that make any changes to variables like 'name' or 'extra' must insure - * that the final string is safe to include directly in the output by using - * check_plain() or filter_xss(). - * - * @see theme_username() - */ -function template_preprocess_username(&$variables) { - $account = $variables['account']; - - $variables['extra'] = ''; - if (empty($account->uid)) { - $variables['uid'] = 0; - if (theme_get_setting('toggle_comment_user_verification')) { - $variables['extra'] = ' (' . t('not verified') . ')'; - } - } - else { - $variables['uid'] = (int)$account->uid; - } - - // Set the name to a formatted name that is safe for printing and - // that won't break tables by being too long. Keep an unshortened, - // unsanitized version, in case other preprocess functions want to implement - // their own shortening logic or add markup. If they do so, they must ensure - // that $variables['name'] is safe for printing. - $name = $variables['name_raw'] = format_username($account); - if (drupal_strlen($name) > 20) { - $name = drupal_substr($name, 0, 15) . '...'; - } - $variables['name'] = check_plain($name); - - $variables['profile_access'] = user_access('access user profiles'); - $variables['link_attributes'] = array(); - // Populate link path and attributes if appropriate. - if ($variables['uid'] && $variables['profile_access']) { - // We are linking to a local user. - $variables['link_attributes'] = array('title' => t('View user profile.')); - $variables['link_path'] = 'user/' . $variables['uid']; - } - elseif (!empty($account->homepage)) { - // Like the 'class' attribute, the 'rel' attribute can hold a - // space-separated set of values, so initialize it as an array to make it - // easier for other preprocess functions to append to it. - $variables['link_attributes'] = array('rel' => array('nofollow')); - $variables['link_path'] = $account->homepage; - $variables['homepage'] = $account->homepage; - } - // We do not want the l() function to check_plain() a second time. - $variables['link_options']['html'] = TRUE; - // Set a default class. - $variables['attributes_array'] = array('class' => array('username')); -} - -/** - * Process variables for theme_username(). - * - * @see theme_username() - */ -function template_process_username(&$variables) { - // Finalize the link_options array for passing to the l() function. - // This is done in the process phase so that attributes may be added by - // modules or the theme during the preprocess phase. - if (isset($variables['link_path'])) { - // $variables['attributes_array'] contains attributes that should be applied - // regardless of whether a link is being rendered or not. - // $variables['link_attributes'] contains attributes that should only be - // applied if a link is being rendered. Preprocess functions are encouraged - // to use the former unless they want to add attributes on the link only. - // If a link is being rendered, these need to be merged. Some attributes are - // themselves arrays, so the merging needs to be recursive. - $variables['link_options']['attributes'] = array_merge_recursive($variables['link_attributes'], $variables['attributes_array']); - } -} - -/** - * Format a username. + * Returns HTML for a username, potentially linked to the user's page. * * @param $variables * An associative array containing: @@ -2050,10 +1949,6 @@ function template_process_username(&$variables) { * - attributes_array: An array of attributes to pass to the * drupal_attributes() function if not linking to the user's page. * - * @return - * A themed HTML string containing the user's name, potentially linked to the - * user's page. - * * @see template_preprocess_username() * @see template_process_username() */ @@ -2074,15 +1969,12 @@ function theme_username($variables) { } /** - * Return a themed progress bar. + * Returns HTML for a progress bar. * * @param $variables * An associative array containing: * - percent: The percentage of the progress. * - message: A string containing information to be displayed. - * - * @return - * A themed HTML string representing the progress bar. */ function theme_progress_bar($variables) { $output = '<div id="progress" class="progress">'; @@ -2095,14 +1987,11 @@ function theme_progress_bar($variables) { } /** - * Create a standard indentation div. Used for drag and drop tables. + * Returns HTML for an indentation div; used for drag and drop tables. * * @param $variables * An associative array containing: * - size: Optional. The number of indentations to create. - * - * @return - * A string containing indentations. */ function theme_indentation($variables) { $output = ''; @@ -2583,3 +2472,80 @@ function template_preprocess_region(&$variables) { $variables['classes_array'][] = $region; $variables['theme_hook_suggestions'][] = 'region__' . $region; } + +/** + * Preprocesses variables for theme_username(). + * + * Modules that make any changes to variables like 'name' or 'extra' must insure + * that the final string is safe to include directly in the output by using + * check_plain() or filter_xss(). + * + * @see template_process_username() + */ +function template_preprocess_username(&$variables) { + $account = $variables['account']; + + $variables['extra'] = ''; + if (empty($account->uid)) { + $variables['uid'] = 0; + if (theme_get_setting('toggle_comment_user_verification')) { + $variables['extra'] = ' (' . t('not verified') . ')'; + } + } + else { + $variables['uid'] = (int)$account->uid; + } + + // Set the name to a formatted name that is safe for printing and + // that won't break tables by being too long. Keep an unshortened, + // unsanitized version, in case other preprocess functions want to implement + // their own shortening logic or add markup. If they do so, they must ensure + // that $variables['name'] is safe for printing. + $name = $variables['name_raw'] = format_username($account); + if (drupal_strlen($name) > 20) { + $name = drupal_substr($name, 0, 15) . '...'; + } + $variables['name'] = check_plain($name); + + $variables['profile_access'] = user_access('access user profiles'); + $variables['link_attributes'] = array(); + // Populate link path and attributes if appropriate. + if ($variables['uid'] && $variables['profile_access']) { + // We are linking to a local user. + $variables['link_attributes'] = array('title' => t('View user profile.')); + $variables['link_path'] = 'user/' . $variables['uid']; + } + elseif (!empty($account->homepage)) { + // Like the 'class' attribute, the 'rel' attribute can hold a + // space-separated set of values, so initialize it as an array to make it + // easier for other preprocess functions to append to it. + $variables['link_attributes'] = array('rel' => array('nofollow')); + $variables['link_path'] = $account->homepage; + $variables['homepage'] = $account->homepage; + } + // We do not want the l() function to check_plain() a second time. + $variables['link_options']['html'] = TRUE; + // Set a default class. + $variables['attributes_array'] = array('class' => array('username')); +} + +/** + * Processes variables for theme_username(). + * + * @see template_preprocess_username() + */ +function template_process_username(&$variables) { + // Finalize the link_options array for passing to the l() function. + // This is done in the process phase so that attributes may be added by + // modules or the theme during the preprocess phase. + if (isset($variables['link_path'])) { + // $variables['attributes_array'] contains attributes that should be applied + // regardless of whether a link is being rendered or not. + // $variables['link_attributes'] contains attributes that should only be + // applied if a link is being rendered. Preprocess functions are encouraged + // to use the former unless they want to add attributes on the link only. + // If a link is being rendered, these need to be merged. Some attributes are + // themselves arrays, so the merging needs to be recursive. + $variables['link_options']['attributes'] = array_merge_recursive($variables['link_attributes'], $variables['attributes_array']); + } +} diff --git a/includes/theme.maintenance.inc b/includes/theme.maintenance.inc index c19dd05db..1a60911b1 100644 --- a/includes/theme.maintenance.inc +++ b/includes/theme.maintenance.inc @@ -87,7 +87,12 @@ function _theme_load_offline_registry($theme, $base_theme = NULL, $theme_engine } /** - * Return a themed list of maintenance tasks to perform. + * Returns HTML for a list of maintenance tasks to perform. + * + * @param $variables + * An associative array containing: + * - items: An associative array of maintenance tasks. + * - active: The key for the currently active maintenance task. * * @ingroup themeable */ @@ -120,7 +125,7 @@ function theme_task_list($variables) { } /** - * Generate a themed installation page. + * Returns HTML for the installation page. * * Note: this function is not themeable. * @@ -180,7 +185,7 @@ function theme_install_page($variables) { } /** - * Generate a themed update page. + * Returns HTML for the update page. * * Note: this function is not themeable. * @@ -226,10 +231,13 @@ function theme_update_page($variables) { } /** - * Generate a report of the results from an operation run via authorize.php. + * Returns HTML for a report of the results from an operation run via authorize.php. * - * @param array $variables + * @param $variables + * An associative array containing: * - messages: An array of result messages. + * + * @ingroup themeable */ function theme_authorize_report($variables) { $messages = $variables['messages']; @@ -251,11 +259,14 @@ function theme_authorize_report($variables) { } /** - * Render a single log message from the authorize.php batch operation. + * Returns HTML for a single log message from the authorize.php batch operation. * * @param $variables + * An associative array containing: * - message: The log message. * - success: A boolean indicating failure or success. + * + * @ingroup themeable */ function theme_authorize_message($variables) { $output = ''; diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module index d7343050e..b6cf40c3b 100644 --- a/modules/aggregator/aggregator.module +++ b/modules/aggregator/aggregator.module @@ -703,15 +703,13 @@ function aggregator_category_load($cid) { } /** - * Format an individual feed item for display in the block. + * Returns HTML for an individual feed item for display in the block. * * @param $variables * An associative array containing: * - item: The item to be displayed. * - feed: Not used. * - * @return - * The item HTML. * @ingroup themeable */ function theme_aggregator_block_item($variables) { diff --git a/modules/aggregator/aggregator.pages.inc b/modules/aggregator/aggregator.pages.inc index f8eb047af..1613a501a 100644 --- a/modules/aggregator/aggregator.pages.inc +++ b/modules/aggregator/aggregator.pages.inc @@ -234,14 +234,12 @@ function aggregator_categorize_items_submit($form, &$form_state) { } /** - * Theme the page list form for assigning categories. + * Returns HTML for the aggregator page list form for assigning categories. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the form. + * - form: A render element representing the form. * - * @return - * The output HTML. * @ingroup themeable */ function theme_aggregator_categorize_items($variables) { @@ -371,13 +369,15 @@ function aggregator_page_rss() { } /** - * Theme the RSS output. + * Prints the RSS page for a feed. * * @param $variables * An associative array containing: * - feeds: An array of the feeds to theme. * - category: A common category, if any, for all the feeds. * + * @return void + * * @ingroup themeable */ function theme_aggregator_page_rss($variables) { @@ -437,12 +437,14 @@ function aggregator_page_opml($cid = NULL) { } /** - * Theme the OPML feed output. + * Prints the OPML page for a feed. * * @param $variables * An associative array containing: * - feeds: An array of the feeds to theme. * + * @return void + * * @ingroup themeable */ function theme_aggregator_page_opml($variables) { diff --git a/modules/book/book.admin.inc b/modules/book/book.admin.inc index d185b0836..7a319430a 100644 --- a/modules/book/book.admin.inc +++ b/modules/book/book.admin.inc @@ -212,10 +212,14 @@ function _book_admin_table_tree($tree, &$form) { } /** - * Theme function for the book administration page form. + * Returns HTML for a book administration form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * - * @ingroup themeable * @see book_admin_table() + * @ingroup themeable */ function theme_book_admin_table($variables) { $form = $variables['form']; diff --git a/modules/book/book.module b/modules/book/book.module index 9d5938331..31401958f 100644 --- a/modules/book/book.module +++ b/modules/book/book.module @@ -338,7 +338,11 @@ function book_block_save($delta = '', $edit = array()) { } /** - * Generate the HTML output for a link to a book title when used as a block title. + * Returns HTML for a link to a book title when used as a block title. + * + * @param $variables + * An associative array containing: + * - link: An array containing title, href and options for the link. * * @ingroup themeable */ diff --git a/modules/color/color.module b/modules/color/color.module index 04d8e9bb4..65cd33608 100644 --- a/modules/color/color.module +++ b/modules/color/color.module @@ -222,7 +222,11 @@ function color_scheme_form($complete_form, &$form_state, $theme) { } /** - * Theme the color form. + * Returns HTML for a theme's color form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/comment/comment.module b/modules/comment/comment.module index 21c16949c..f9305e808 100644 --- a/modules/comment/comment.module +++ b/modules/comment/comment.module @@ -568,10 +568,8 @@ function comment_new_page_count($num_comments, $new_replies, $node) { } /** - * Returns a formatted list of recent comments to be displayed in the comment block. + * Returns HTML for a list of recent comments to be displayed in the comment block. * - * @return - * The comment list HTML. * @ingroup themeable */ function theme_comment_block() { @@ -2204,7 +2202,7 @@ function template_preprocess_comment(&$variables) { } /** - * Theme a "you can't post comments" notice. + * Returns HTML for a "you can't post comments" notice. * * @param $variables * An associative array containing: diff --git a/modules/dashboard/dashboard.module b/modules/dashboard/dashboard.module index c90f65d75..1ef9ef195 100644 --- a/modules/dashboard/dashboard.module +++ b/modules/dashboard/dashboard.module @@ -366,13 +366,12 @@ function dashboard_update() { } /** - * Theme the entire dashboard. + * Returns HTML for the entire dashboard. * * @param $variables - * - element: An associative array containing the properties of the dashboard region - * element. Properties used: #dashboard_region, #children - * @return - * A string representing the themed dashboard. + * An associative array containing: + * - element: A render element containing the properties of the dashboard + * region element, #dashboard_region and #children. * * @ingroup themeable */ @@ -383,15 +382,11 @@ function theme_dashboard($variables) { } /** - * Theme the page containing the dashboard. + * Returns HTML for the non-customizable part of the dashboard page. * * @param $variables * An associative array containing: - * - elements: An associative array containing the properties of the element. - * Properties used: #message - * @return - * A themed HTML string representing the non-customizable part of the - * dashboard page. + * - element: A render element containing a #message. * * @ingroup themeable */ @@ -402,13 +397,12 @@ function theme_dashboard_admin($variables) { } /** - * Theme a generic dashboard region. + * Returns HTML for a generic dashboard region. * * @param $variables - * - element: An associative array containing the properties of the dashboard region - * element. Properties used: #dashboard_region, #children - * @return - * A string representing the themed dashboard region. + * An associative array containing: + * - element: A render element containing the properties of the dashboard + * region element, #dashboard_region and #children. * * @ingroup themeable */ @@ -425,13 +419,11 @@ function theme_dashboard_region($variables) { } /** - * Theme a set of disabled blocks, for display in dashboard customization mode. + * Returns HTML for a set of disabled blocks, for display in dashboard customization mode. * * @param $variables + * An associative array containing: * - blocks: An array of block objects from _block_rehash(). - * @return - * A string representing the disabled blocks region of the dashboard - * customization page. * * @ingroup themeable */ @@ -447,12 +439,11 @@ function theme_dashboard_disabled_blocks($variables) { } /** - * Theme a disabled block, for display in dashboard customization mode. + * Returns HTML for a disabled block, for display in dashboard customization mode. * * @param $variables + * An associative array containing: * - block: A block object from _block_rehash(). - * @return - * A string representing the disabled block. * * @ingroup themeable */ diff --git a/modules/dblog/dblog.admin.inc b/modules/dblog/dblog.admin.inc index 4f344f577..1f5ba8833 100644 --- a/modules/dblog/dblog.admin.inc +++ b/modules/dblog/dblog.admin.inc @@ -251,7 +251,7 @@ function dblog_filters() { } /** - * Formats a log message for display. + * Returns HTML for a log message. * * @param $variables * An associative array containing: diff --git a/modules/field/field.form.inc b/modules/field/field.form.inc index b5be9224c..5fd367a07 100644 --- a/modules/field/field.form.inc +++ b/modules/field/field.form.inc @@ -231,10 +231,16 @@ function field_multiple_value_form($field, $instance, $langcode, $items, &$form, } /** - * Theme an individual form element. + * Returns HTML for an individual form element. * * Combine multiple values into a table with drag-n-drop reordering. * TODO : convert to a template. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the form element. + * + * @ingroup themeable */ function theme_field_multiple_value_form($variables) { $element = $variables['element']; diff --git a/modules/field/field.module b/modules/field/field.module index c3765cfaa..d470c9fd7 100644 --- a/modules/field/field.module +++ b/modules/field/field.module @@ -790,7 +790,7 @@ function template_process_field(&$variables, $hook) { */ /** - * Returns a themed field. + * Returns HTML for a field. * * This is the default theme implementation to display the value of a field. * Theme developers who are comfortable with overriding theme functions may do @@ -831,6 +831,18 @@ function template_process_field(&$variables, $hook) { * the exact performance impact depends on the server configuration and the * details of the website. * + * @param $variables + * An associative array containing: + * - label_hidden: A boolean indicating to show or hide the field label. + * - title_attributes: A string containing the attributes for the title. + * - label: The label for the field. + * - content_attributes: A string containing the attaributes for the content's + * div. + * - items: An array of field items. + * - item_attributes: An array of attributes for each item. + * - classes: A string containing the classes for the wrapping div. + * - attributes: A string containing the attributes for the wrapping div. + * * @see template_preprocess_field() * @see template_process_field() * @see field.tpl.php diff --git a/modules/field/modules/options/options.module b/modules/field/modules/options/options.module index 72a713afd..24ab04758 100644 --- a/modules/field/modules/options/options.module +++ b/modules/field/modules/options/options.module @@ -366,8 +366,15 @@ function options_field_widget_error($element, $error, $form, &$form_state) { } /** - * Theme the label for the empty value for options that are not required. - * The default theme will display N/A for a radio list and blank for a select. + * Returns HTML for the label for the empty value for options that are not required. + * + * The default theme will display N/A for a radio list and blank for a select. + * + * @param $variables + * An associative array containing: + * - instance: An array representing the widget requesting the options. + * + * @ingroup themeable */ function theme_options_none($variables) { $instance = $variables['instance']; diff --git a/modules/file/file.field.inc b/modules/file/file.field.inc index 57c47ae1e..ddd449e7e 100644 --- a/modules/file/file.field.inc +++ b/modules/file/file.field.inc @@ -696,7 +696,13 @@ function file_field_widget_process_multiple($element, &$form_state, $form) { } /** - * Theme an individual file upload widget. + * Returns HTML for an individual file upload widget. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the widget. + * + * @ingroup themeable */ function theme_file_widget($variables) { $element = $variables['element']; @@ -715,7 +721,13 @@ function theme_file_widget($variables) { } /** - * Theme a group of file upload widgets. + * Returns HTML for a group of file upload widgets. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the widgets. + * + * @ingroup themeable */ function theme_file_widget_multiple($variables) { $element = $variables['element']; @@ -800,7 +812,7 @@ function theme_file_widget_multiple($variables) { } /** - * Generate help text based on upload validators. + * Returns HTML for help text based on file upload validators. * * @param $variables * An associative array containing: @@ -809,8 +821,7 @@ function theme_file_widget_multiple($variables) { * - upload_validators: An array of upload validators as used in * $element['#upload_validators']. * - * @return - * A string suitable for a file field description. + * @ingroup themeable */ function theme_file_upload_help($variables) { $description = $variables['description']; @@ -882,7 +893,13 @@ function file_field_formatter_view($entity_type, $entity, $field, $instance, $la } /** - * Theme function for the 'table' formatter. + * Returns HTML for a file attachments table. + * + * @param $variables + * An associative array containing: + * - items: An array of file attachments. + * + * @ingroup themeable */ function theme_file_formatter_table($variables) { $header = array(t('Attachment'), t('Size')); diff --git a/modules/file/file.module b/modules/file/file.module index b3153e647..b925d7c2e 100644 --- a/modules/file/file.module +++ b/modules/file/file.module @@ -607,7 +607,13 @@ function file_managed_file_save_upload($element) { } /** - * Theme a managed file element. + * Returns HTML for a managed file element. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the file. + * + * @ingroup themeable */ function theme_file_managed_file($variables) { $element = $variables['element']; @@ -621,11 +627,13 @@ function theme_file_managed_file($variables) { } /** - * Output a link to a file. + * Returns HTML for a link to a file. * * @param $variables * An associative array containing: * - file: A file object to which the link will be created. + * + * @ingroup themeable */ function theme_file_link($variables) { $file = $variables['file']; @@ -654,11 +662,13 @@ function theme_file_link($variables) { } /** - * Return an image with an appropriate icon for the given file. + * Returns HTML for an image with an appropriate icon for the given file. * * @param $variables * An associative array containing: * - file: A file object for which to make an icon. + * + * @ingroup themeable */ function theme_file_icon($variables) { $file = $variables['file']; diff --git a/modules/filter/filter.admin.inc b/modules/filter/filter.admin.inc index 257919344..5e6254c72 100644 --- a/modules/filter/filter.admin.inc +++ b/modules/filter/filter.admin.inc @@ -56,7 +56,11 @@ function filter_admin_overview_submit($form, &$form_state) { } /** - * Theme the text format administration overview form. + * Returns HTML for the text format administration overview form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -233,7 +237,11 @@ function filter_admin_format_form($form, &$form_state, $format) { } /** - * Theme text format filter order form elements as tabledrag. + * Returns HTML for a text format's filter order form. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/filter/filter.module b/modules/filter/filter.module index a69d26031..29be14894 100644 --- a/modules/filter/filter.module +++ b/modules/filter/filter.module @@ -933,15 +933,11 @@ function filter_form_access_denied($element) { } /** - * Render a text format-enabled form element. + * Returns HTML for a text format-enabled form element. * * @param $variables * An associative array containing: - * - element: An associative array containing the properties of the element. - * Properties used: #children, #description - * - * @return - * A string representing the form element. + * - element: A render element containing #children and #description. * * @ingroup themeable */ @@ -1103,7 +1099,7 @@ function filter_dom_serialize_escape_cdata_element($dom_document, $dom_element, } /** - * Format a link to the more extensive filter tips. + * Returns HTML for a link to the more extensive filter tips. * * @ingroup themeable */ @@ -1112,7 +1108,7 @@ function theme_filter_tips_more_info() { } /** - * Format guidelines for a text format. + * Returns HTML for guidelines for a text format. * * @param $variables * An associative array containing: diff --git a/modules/filter/filter.pages.inc b/modules/filter/filter.pages.inc index ce3d842d3..e018e819d 100644 --- a/modules/filter/filter.pages.inc +++ b/modules/filter/filter.pages.inc @@ -23,7 +23,7 @@ function filter_tips_long() { /** - * Render HTML for a set of filter tips. + * Returns HTML for a set of filter tips. * * @param $variables * An associative array containing: diff --git a/modules/forum/forum.admin.inc b/modules/forum/forum.admin.inc index 49cb555ec..607089f66 100644 --- a/modules/forum/forum.admin.inc +++ b/modules/forum/forum.admin.inc @@ -102,14 +102,15 @@ function forum_form_submit($form, &$form_state) { } /** - * Theme forum forms. + * Returns HTML for a forum form. * * By default this does not alter the appearance of a form at all, * but is provided as a convenience for themers. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the form. + * - form: A render element representing the form. + * * @ingroup themeable */ function theme_forum_form($variables) { diff --git a/modules/image/image.admin.inc b/modules/image/image.admin.inc index 3ca88d5cf..8ef98a84a 100644 --- a/modules/image/image.admin.inc +++ b/modules/image/image.admin.inc @@ -623,7 +623,7 @@ function image_rotate_form($data) { } /** - * Display the page containing the list of image styles. + * Returns HTML for the page containing the list of image styles. * * @param $variables * An associative array containing: @@ -674,11 +674,11 @@ function theme_image_style_list($variables) { } /** - * Theme callback for listing the effects within a specific image style. + * Returns HTML for a listing of the effects within a specific image style. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the effects group. + * - form: A render element representing the form. * * @ingroup themeable */ @@ -733,7 +733,7 @@ function theme_image_style_effects($variables) { } /** - * Theme callback for displaying a preview of an image style. + * Returns HTML for a preview of an image style. * * @param $variables * An associative array containing: @@ -809,11 +809,11 @@ function theme_image_style_preview($variables) { } /** - * Theme callback for displaying a grid of checkboxes. + * Returns HTML for a 3x3 grid of checkboxes for image anchors. * * @param $variables * An associative array containing: - * - element: A Form API element containing radio buttons. + * - element: A render element containing radio buttons. * * @ingroup themeable */ @@ -836,7 +836,7 @@ function theme_image_anchor($variables) { } /** - * Theme callback for image resize effect summary output. + * Returns HTML for a summary of an image resize effect. * * @param $variables * An associative array containing: @@ -856,7 +856,7 @@ function theme_image_resize_summary($variables) { } /** - * Theme callback for image scale effect summary output. + * Returns HTML for a summary of an image scale effect. * * @param $variables * An associative array containing: @@ -870,7 +870,7 @@ function theme_image_scale_summary($variables) { } /** - * Theme callback for image crop effect summary output. + * Returns HTML for a summary of an image crop effect. * * @param $variables * An associative array containing: @@ -883,7 +883,7 @@ function theme_image_crop_summary($variables) { } /** - * Theme callback for image rotate effect summary output. + * Returns HTML for a summary of an image rotate effect. * * @param $variables * An associative array containing: diff --git a/modules/image/image.field.inc b/modules/image/image.field.inc index 20c1294d4..47a91c01d 100644 --- a/modules/image/image.field.inc +++ b/modules/image/image.field.inc @@ -390,7 +390,13 @@ function image_field_widget_process($element, &$form_state, $form) { } /** - * Theme the display of the image field widget. + * Returns HTML for an image field widget. + * + * @param $variables + * An associative array containing: + * - element: A render element representing the image field widget. + * + * @ingroup themeable */ function theme_image_widget($variables) { $element = $variables['element']; @@ -490,7 +496,15 @@ function image_field_formatter_view($entity_type, $entity, $field, $instance, $l } /** - * Theme function for image field formatters. + * Returns HTML for an image field formatter. + * + * @param $variables + * An associative array containing: + * - item: An array of image data. + * - image_style: An optional image style. + * - path: An array containing the link 'path' and link 'options'. + * + * @ingroup themeable */ function theme_image_formatter($variables) { $item = $variables['item']; diff --git a/modules/image/image.module b/modules/image/image.module index a1d7327f4..e2a906654 100644 --- a/modules/image/image.module +++ b/modules/image/image.module @@ -1010,7 +1010,7 @@ function image_effect_apply($image, $effect) { } /** - * Return a themed image using a specific image style. + * Returns HTML for an image using a specific image style. * * @param $variables * An associative array containing: @@ -1025,8 +1025,6 @@ function image_effect_apply($image, $effect) { * - getsize: If set to TRUE, the image's dimension are fetched and added as * width/height attributes. * - * @return - * A string containing the image tag. * @ingroup themeable */ function theme_image_style($variables) { diff --git a/modules/locale/locale.admin.inc b/modules/locale/locale.admin.inc index b19fce111..79ffbb3d6 100644 --- a/modules/locale/locale.admin.inc +++ b/modules/locale/locale.admin.inc @@ -51,14 +51,11 @@ function locale_languages_overview_form() { } /** - * Theme the language overview form. + * Returns HTML for the language overview form. * * @param $variables * An associative array containing: - * - form: @todo: document - * - * @return - * A themed HTML string representing the form. + * - form: A render element representing the form. * * @ingroup themeable */ @@ -569,7 +566,11 @@ function _locale_languages_configure_form_language_table(&$form, $type) { } /** - * Theme the language configure form. + * Returns HTML for a language configuration form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -1278,7 +1279,11 @@ function locale_translate_delete_form_submit($form, &$form_state) { */ /** - * Theme locale date format form. + * Returns HTML for a locale date format form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/menu/menu.admin.inc b/modules/menu/menu.admin.inc index c73af82a4..3483ee6d2 100644 --- a/modules/menu/menu.admin.inc +++ b/modules/menu/menu.admin.inc @@ -25,7 +25,14 @@ function menu_overview_page() { } /** - * Theme the menu title and description for admin page + * Returns HTML for a menu title and description for the menu overview page. + * + * @param $variables + * An associative array containing: + * - title: The menu's title. + * - description: The menu's description. + * + * @ingroup themeable */ function theme_menu_admin_overview($variables) { $output = check_plain($variables['title']); @@ -177,7 +184,11 @@ function menu_overview_form_submit($form, &$form_state) { } /** - * Theme the menu overview form into a table. + * Returns HTML for the menu overview form into a table. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/node/content_types.inc b/modules/node/content_types.inc index 70112c473..8bca4653b 100644 --- a/modules/node/content_types.inc +++ b/modules/node/content_types.inc @@ -54,6 +54,17 @@ function node_overview_types() { return $build; } +/** + * Returns HTML for a node type description for the content type admin overview page. + * + * @param $variables + * An associative array containing: + * - name: The human-readable name of the content type. + * - type: An object containing the 'type' (machine name) and 'description' of + * the content type. + * + * @ingroup themeable + */ function theme_node_admin_overview($variables) { $name = $variables['name']; $type = $variables['type']; diff --git a/modules/node/node.admin.inc b/modules/node/node.admin.inc index 4dd932307..11a818a97 100644 --- a/modules/node/node.admin.inc +++ b/modules/node/node.admin.inc @@ -204,7 +204,11 @@ function node_filter_form() { } /** - * Theme node administration filter selector. + * Returns HTML for a node administration filter selector. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/node/node.module b/modules/node/node.module index c5b069d99..d9c137996 100644 --- a/modules/node/node.module +++ b/modules/node/node.module @@ -1695,7 +1695,11 @@ function node_user_delete($account) { } /** - * Theme the content ranking part of the search settings admin page. + * Returns HTML for the content ranking part of the search settings admin page. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -2129,10 +2133,12 @@ function node_get_recent($number = 10) { } /** - * Returns a formatted list of recent nodes. + * Returns HTML for a list of recent content. + * + * @param $variables + * An associative array containing: + * - nodes: An array of recent node objects. * - * @return - * The recent content table HTML. * @ingroup themeable */ function theme_node_recent_block($variables) { @@ -2168,10 +2174,12 @@ function theme_node_recent_block($variables) { } /** - * Returns a formatted recent node to be displayed in the recent content block. + * Returns HTML for a recent node to be displayed in the recent content block. + * + * @param $variables + * An associative array containing: + * - node: A node object. * - * @return - * The recent content node's HTML. * @ingroup themeable */ function theme_node_recent_content($variables) { diff --git a/modules/node/node.pages.inc b/modules/node/node.pages.inc index a6d5c0a0b..d18e7a779 100644 --- a/modules/node/node.pages.inc +++ b/modules/node/node.pages.inc @@ -28,7 +28,11 @@ function node_add_page() { } /** - * Display the list of available node types for node creation. + * Returns HTML for a list of available node types for node creation. + * + * @param $variables + * An associative array containing: + * - content: An array of content types. * * @ingroup themeable */ @@ -340,7 +344,7 @@ function node_preview($node) { } /** - * Display a node preview for display during node creation and editing. + * Returns HTML for a node preview for display during node creation and editing. * * @param $variables * An associative array containing: diff --git a/modules/poll/poll.module b/modules/poll/poll.module index 7d012e6fd..bcd8e9e8d 100644 --- a/modules/poll/poll.module +++ b/modules/poll/poll.module @@ -779,7 +779,11 @@ function poll_view_results($node, $view_mode, $block = FALSE) { /** - * Theme the admin poll form for choices. + * Returns HTML for an admin poll form for choices. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/profile/profile.admin.inc b/modules/profile/profile.admin.inc index d6e535598..1a2f792fc 100644 --- a/modules/profile/profile.admin.inc +++ b/modules/profile/profile.admin.inc @@ -91,10 +91,14 @@ function profile_admin_overview_submit($form, &$form_state) { } /** - * Theme the profile field overview into a drag and drop enabled table. + * Returns HTML for the profile field overview form into a drag and drop enabled table. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * - * @ingroup themeable * @see profile_admin_overview() + * @ingroup themeable */ function theme_profile_admin_overview($variables) { $form = $variables['form']; diff --git a/modules/rdf/rdf.module b/modules/rdf/rdf.module index 0c6ea4f8a..b7d5b4884 100644 --- a/modules/rdf/rdf.module +++ b/modules/rdf/rdf.module @@ -721,7 +721,7 @@ function rdf_preprocess_image(&$variables) { } /** - * Wraps a template variable in an HTML element with the desired attributes. + * Returns HTML for a template variable wrapped in an HTML element with the desired attributes. * * This is called by rdf_process() shortly before the theme system renders * a template file. It is called once for each template variable for which @@ -732,6 +732,14 @@ function rdf_preprocess_image(&$variables) { * that need containing attributes are routed through this function, allowing * the template file to receive properly wrapped variables. * + * Tip for themers: if you're already outputting a wrapper element around a + * particular template variable in your template file and if you don't want + * an extra wrapper element, you can override this function to not wrap that + * variable and instead print the following inside your template file: + * @code + * drupal_attributes($rdf_template_variable_attributes_array[$variable_name]) + * @endcode + * * @param $variables * An associative array containing: * - content: A string of content to be wrapped with attributes. @@ -760,20 +768,7 @@ function rdf_preprocess_image(&$variables) { * hook_preprocess_rdf_template_variable_wrapper() and set 'inline' * accordingly. * - * @return - * A string containing the wrapped content. The template receives the for its - * variable instead of the original content. - * - * Tip for themers: if you're already outputting a wrapper element around a - * particular template variable in your template file and if you don't want - * an extra wrapper element, you can override this function to not wrap that - * variable and instead print the following inside your template file: - * @code - * drupal_attributes($rdf_template_variable_attributes_array[$variable_name]) - * @endcode - * * @see rdf_process() - * * @ingroup themeable * @ingroup rdf */ @@ -787,7 +782,7 @@ function theme_rdf_template_variable_wrapper($variables) { } /** - * Outputs a series of empty spans for exporting RDF metadata in RDFa. + * Returns HTML for a series of empty spans for exporting RDF metadata in RDFa. * * Sometimes it is useful to export data which is not semantically present in * the HTML output. For example, a hierarchy of comments is visible for a human @@ -801,11 +796,7 @@ function theme_rdf_template_variable_wrapper($variables) { * corresponds to its own set of attributes, and therefore, needs its own * element. * - * @return - * A string of HTML containing markup that can be understood by RDFa parsers. - * * @see rdf_process() - * * @ingroup themeable * @ingroup rdf */ diff --git a/modules/search/search.pages.inc b/modules/search/search.pages.inc index 02d283e70..6bbb88942 100644 --- a/modules/search/search.pages.inc +++ b/modules/search/search.pages.inc @@ -47,15 +47,14 @@ function search_view($type = 'node') { } /** - * Theme the listing of search results + * Returns HTML for a listing of search results. * * @param $variables * An associative array containing: * - title: The subject of the listing. * - content: The content of the listing. * - * @return - * A string containing the listing output. + * @ingroup themeable */ function theme_search_results_listing($variables) { $output = '<h2 class="title">' . $variables['title'] . '</h2><div>' . $variables['content'] . '</div>'; diff --git a/modules/shortcut/shortcut.admin.inc b/modules/shortcut/shortcut.admin.inc index bb9f17da3..2db30f220 100644 --- a/modules/shortcut/shortcut.admin.inc +++ b/modules/shortcut/shortcut.admin.inc @@ -294,17 +294,14 @@ function shortcut_set_customize_submit($form, &$form_state) { } /** - * Themes the shortcut set customization form. + * Returns HTML for a shortcut set customization form. * * @param $variables * An associative array containing: - * - form: An array representing the form. + * - form: A render element representing the form. * - * @return - * A themed HTML string representing the content of the form. - * - * @ingroup themeable * @see shortcut_set_customize() + * @ingroup themeable */ function theme_shortcut_set_customize($variables) { $form = $variables['form']; diff --git a/modules/simpletest/simpletest.pages.inc b/modules/simpletest/simpletest.pages.inc index 72d01e4a9..980075e84 100644 --- a/modules/simpletest/simpletest.pages.inc +++ b/modules/simpletest/simpletest.pages.inc @@ -58,14 +58,13 @@ function simpletest_test_form($form) { } /** - * Theme the test list generated by simpletest_test_form() into a table. + * Returns HTML for a test list generated by simpletest_test_form() into a table. * * @param $variables * An associative array containing: - * - table: Form array that represent a table. + * - table: A render element representing the table. * - * @return - * HTML output. + * @ingroup themeable */ function theme_simpletest_test_table($variables) { $table = $variables['table']; @@ -366,9 +365,13 @@ function simpletest_result_form_submit($form, &$form_state) { } /** - * Add wrapper div with class based on summary status. + * Returns HTML for the summary status of a simpletest result. * - * @return HTML output. + * @param $variables + * An associative array containing: + * - form: A render element representing the form. + * + * @ingroup themeable */ function theme_simpletest_result_summary($variables) { $form = $variables['form']; diff --git a/modules/syslog/syslog.module b/modules/syslog/syslog.module index 1ee2ef6d8..5d95493c5 100644 --- a/modules/syslog/syslog.module +++ b/modules/syslog/syslog.module @@ -95,7 +95,23 @@ function syslog_theme() { } /** - * Format a system log entry. + * Returns a string for a system log entry. + * + * @param $variables + * An associative array containing: + * - entry: An array containing the data about the log entry, containing: + * - timestamp: The date and time of the log entry. + * - type: The type of log entry. + * - ip: The IP address. + * - request_uri: The requested URI. + * - referer: The URL which referred to the request URI. + * - user: The user object associated with the log entry. + * - link: A link accociated with the log entry. + * - variables: A string representing the data to log. + * - message: If variables is not specified, a string for the log message. + * + * @return + * A string containing a pipe-delimited "|" log message. * * @ingroup themeable */ diff --git a/modules/system/system.admin.inc b/modules/system/system.admin.inc index 3ca45af48..aff0429b3 100644 --- a/modules/system/system.admin.inc +++ b/modules/system/system.admin.inc @@ -1982,7 +1982,11 @@ function system_date_time_settings() { } /** - * Theme function for date settings form. + * Returns HTML for the date settings form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -2270,12 +2274,12 @@ function system_batch_page() { } /** - * This function formats an administrative block for display. + * Returns HTML for an administrative block for display. * * @param $variables * An associative array containing: - * - block: An array containing information about the block. It should - * include a 'title', a 'description' and a formatted 'content'. + * - block: An array containing information about the block. It should include + * a 'title', a 'description' and a formatted 'content'. * * @ingroup themeable */ @@ -2315,7 +2319,7 @@ EOT; } /** - * This function formats the content of an administrative block. + * Returns HTML for the content of an administrative block. * * @param $variables * An associative array containing: @@ -2350,14 +2354,14 @@ function theme_admin_block_content($variables) { } /** - * This function formats an administrative page for viewing. + * Returns HTML for an administrative page. * * @param $variables * An associative array containing: * - blocks: An array of blocks to display. Each array should include a - * 'title', a 'description', a formatted 'content' and a - * 'position' which will control which container it will be - * in. This is usually 'left' or 'right'. + * 'title', a 'description', a formatted 'content' and a 'position' which + * will control which container it will be in. This is usually 'left' or + * 'right'. * * @ingroup themeable */ @@ -2393,7 +2397,7 @@ function theme_admin_page($variables) { } /** - * Theme output of the dashboard page. + * Returns HTML for the output of the dashboard page. * * @param $variables * An associative array containing: @@ -2445,7 +2449,7 @@ function theme_system_admin_by_module($variables) { } /** - * Theme requirements status report. + * Returns HTML for the status report. * * @param $variables * An associative array containing: @@ -2486,11 +2490,11 @@ function theme_status_report($variables) { } /** - * Theme callback for the modules form. + * Returns HTML for the modules form. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the form. + * - form: A render element representing the form. * * @ingroup themeable */ @@ -2533,32 +2537,26 @@ function theme_system_modules_fieldset($variables) { } /** - * Themes an incompatible message. - * - * @ingroup themeable + * Returns HTML for a message about incompatible modules. * * @param $variables * An associative array containing: * - message: The form array representing the currently disabled modules. * - * @return - * An HTML string for the message. + * @ingroup themeable */ function theme_system_modules_incompatible($variables) { return '<div class="incompatible">' . $variables['message'] . '</div>'; } /** - * Themes a table of currently disabled modules. - * - * @ingroup themeable + * Returns HTML for a table of currently disabled modules. * * @param $variables * An associative array containing: - * - form: The form array representing the currently disabled modules. + * - form: A render element representing the form. * - * @return - * An HTML string representing the table. + * @ingroup themeable */ function theme_system_modules_uninstall($variables) { $form = $variables['form']; @@ -2591,7 +2589,7 @@ function theme_system_modules_uninstall($variables) { } /** - * Theme function for the system themes form. + * Returns HTML for the Appearance page. * * @param $variables * An associative array containing: diff --git a/modules/system/system.module b/modules/system/system.module index 822c559ec..d068c40fd 100644 --- a/modules/system/system.module +++ b/modules/system/system.module @@ -3138,16 +3138,16 @@ function system_timezone($abbreviation = '', $offset = -1, $is_daylight_saving_t } /** - * Format the Powered by Drupal text. + * Returns HTML for the Powered by Drupal text. * * @ingroup themeable */ -function theme_system_powered_by($variables) { +function theme_system_powered_by() { return '<span>' . t('Powered by <a href="@poweredby">Drupal</a>', array('@poweredby' => 'http://drupal.org')) . '</span>'; } /** - * Display the link to show or hide inline help descriptions. + * Returns HTML for a link to show or hide inline help descriptions. * * @ingroup themeable */ @@ -3627,14 +3627,15 @@ function system_archiver_info() { } /** - * Theme confirmation forms. + * Returns HTML for a confirmation form. * * By default this does not alter the appearance of a form at all, * but is provided as a convenience for themers. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the form. + * - form: A render element representing the form. + * * @ingroup themeable */ function theme_confirm_form($variables) { @@ -3642,14 +3643,15 @@ function theme_confirm_form($variables) { } /** - * Theme function for the system settings form. + * Returns HTML for a system settings form. * * By default this does not alter the appearance of a form at all, * but is provided as a convenience for themers. * * @param $variables * An associative array containing: - * - form: An associative array containing the structure of the form. + * - form: A render element representing the form. + * * @ingroup themeable */ function theme_system_settings_form($variables) { diff --git a/modules/taxonomy/taxonomy.admin.inc b/modules/taxonomy/taxonomy.admin.inc index 5ad7538ae..b8b6b3b5f 100644 --- a/modules/taxonomy/taxonomy.admin.inc +++ b/modules/taxonomy/taxonomy.admin.inc @@ -52,10 +52,14 @@ function taxonomy_overview_vocabularies_submit($form, &$form_state) { } /** - * Theme the vocabulary overview as a sortable list of vocabularies. + * Returns HTML for the vocabulary overview form as a sortable list of vocabularies. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * - * @ingroup themeable * @see taxonomy_overview_vocabularies() + * @ingroup themeable */ function theme_taxonomy_overview_vocabularies($variables) { $form = $variables['form']; @@ -513,10 +517,14 @@ function taxonomy_overview_terms_submit($form, &$form_state) { } /** - * Theme the terms overview as a sortable list of terms. + * Returns HTML for a terms overview form as a sortable list of terms. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * - * @ingroup themeable * @see taxonomy_overview_terms() + * @ingroup themeable */ function theme_taxonomy_overview_terms($variables) { $form = $variables['form']; diff --git a/modules/trigger/trigger.admin.inc b/modules/trigger/trigger.admin.inc index 8e462fe98..c83a95979 100644 --- a/modules/trigger/trigger.admin.inc +++ b/modules/trigger/trigger.admin.inc @@ -272,15 +272,12 @@ function trigger_assign_form_submit($form, &$form_state) { } /** - * Displays actions assigned to this hook in a table. + * Returns HTML for the form showing actions assigned to a trigger. * * @param $variables * An associative array containing: * - element: The fieldset including all assigned actions. * - * @return - * The rendered form with the table prepended. - * * @ingroup themeable */ function theme_trigger_display($variables) { diff --git a/modules/update/update.manager.inc b/modules/update/update.manager.inc index f72ce44c1..595c64222 100644 --- a/modules/update/update.manager.inc +++ b/modules/update/update.manager.inc @@ -256,10 +256,11 @@ function update_manager_update_form($form, $form_state = array(), $context) { } /** - * Theme the first page in the update manager wizard to select projects. + * Returns HTML for the first page in the update manager wizard to select projects. * * @param $variables - * form: The form + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/update/update.module b/modules/update/update.module index af81f6b01..faa79c567 100644 --- a/modules/update/update.module +++ b/modules/update/update.module @@ -606,14 +606,15 @@ function _update_project_status_sort($a, $b) { } /** - * Render the HTML to display the last time we checked for update data. + * Returns HTML for the last time we checked for update data. * * In addition to properly formating the given timestamp, this function also * provides a "Check manually" link that refreshes the available update and * redirects back to the same page. * * @param $variables - * 'last': The timestamp when the site last checked for available updates. + * An associative array containing: + * - 'last': The timestamp when the site last checked for available updates. * * @see theme_update_report() * @see theme_update_available_updates_form() diff --git a/modules/update/update.report.inc b/modules/update/update.report.inc index b33cea897..6a9d60d1b 100644 --- a/modules/update/update.report.inc +++ b/modules/update/update.report.inc @@ -21,7 +21,11 @@ function update_status() { } /** - * Theme project status report. + * Returns HTML for the project status report. + * + * @param $variables + * An associative array containing: + * - data: An array of data about each project's status. * * @ingroup themeable */ @@ -244,7 +248,7 @@ function theme_update_report($variables) { } /** - * Generate the HTML for the label to display for a project's update status. + * Returns HTML for a label to display for a project's update status. * * @param $variables * An associative array containing: @@ -273,7 +277,17 @@ function theme_update_status_label($variables) { } /** - * Theme the version display of a project. + * Returns HTML for the version display of a project. + * + * @param $variables + * An associative array containing: + * - version: An array of data about the latest released version, containing: + * - version: The version number. + * - release_link: The URL for the release notes. + * - date: The date of the release. + * - download_link: The URL for the downloadable file. + * - tag: The title of the project. + * - class: A string containing extra classes for the wrapping table. * * @ingroup themeable */ diff --git a/modules/user/user.admin.inc b/modules/user/user.admin.inc index 8c8f4387c..ee100630c 100644 --- a/modules/user/user.admin.inc +++ b/modules/user/user.admin.inc @@ -733,7 +733,11 @@ function user_admin_permissions_submit($form, &$form_state) { } /** - * Theme the administer permissions page. + * Returns HTML for the administer permissions page. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -770,7 +774,7 @@ function theme_user_admin_permissions($variables) { } /** - * Theme an individual permission description. + * Returns HTML for an individual permission description. * * @param $variables * An associative array containing: @@ -861,7 +865,11 @@ function user_admin_roles_order_submit($form, &$form_state) { } /** - * Theme the role order and new role form. + * Returns HTML for the role order and new role form. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ @@ -1007,7 +1015,11 @@ function user_admin_role_delete_confirm_submit($form, &$form_state) { } /** - * Theme user administration filter selector. + * Returns HTML for the user administration filter selector. + * + * @param $variables + * An associative array containing: + * - form: A render element representing the form. * * @ingroup themeable */ diff --git a/modules/user/user.module b/modules/user/user.module index 463dfa5bc..26d9edfdd 100644 --- a/modules/user/user.module +++ b/modules/user/user.module @@ -1338,7 +1338,7 @@ function template_preprocess_user_picture(&$variables) { } /** - * Make a list of users. + * Returns HTML for a list of users. * * @param $variables * An associative array containing: @@ -3116,7 +3116,11 @@ function user_comment_view($comment) { } /** - * Theme output of user signature. + * Returns HTML for a user signature. + * + * @param $variables + * An associative array containing: + * - signature: The user's signature. * * @ingroup themeable */ |