Commit 3c3cee28 authored by Dries's avatar Dries

- Patch #716496 by JohnAlbin: documentation updates for theme functions.

parent f8e14898
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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) {
......
......@@ -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.