Commit 3c3cee28 authored by Dries's avatar Dries

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

parent f8e14898
This diff is collapsed.
......@@ -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) {
......
This diff is collapsed.
......@@ -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 = '';
......
......@@ -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) {
......
......@@ -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) {
......
......@@ -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'];
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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:
......
......@@ -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
*/
......
......@@ -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:
......
......@@ -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'];
......
......@@ -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
......
......@@ -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'];
......
......@@ -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'));
......
......@@ -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'];
......
......@@ -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
*/
......
......@@ -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:
......
......@@ -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:
......
......@@ -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) {
......
......@@ -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) {
}