Drupal's presentation layer is a pluggable system known as the theme layer. Each theme can take control over most of Drupal's output, and has complete control over the CSS.
Inside Drupal, the theme layer is utilized by the use of the theme() function, which is passed the name of a component (the theme hook) and several arguments. For example, theme('table', $header, $rows); Additionally, the theme() function can take an array of theme hooks, which can be used to provide 'fallback' implementations to allow for more specific control of output. For example, the function: theme(array('table__foo', 'table'), $header, $rows) would look to see if 'table__foo' is registered anywhere; if it is not, it would 'fall back' to the generic 'table' implementation. This can be used to attach specific theme functions to named objects, allowing the themer more control over specific types of output.
As of Drupal 6, every theme hook is required to be registered by the module that owns it, so that Drupal can tell what to do with it and to make it simple for themes to identify and override the behavior for these calls.
The theme hooks are registered via hook_theme(), which returns an array of arrays with information about the hook. It describes the arguments the function or template will need, and provides defaults for the template in case they are not filled in. If the default implementation is a function, by convention it is named theme_HOOK().
Each module should provide a default implementation for theme_hooks that it registers. This implementation may be either a function or a template; if it is a function it must be specified via hook_theme(). By convention, default implementations of theme hooks are named theme_HOOK. Default template implementations are stored in the module directory.
Drupal's default template renderer is a simple PHP parsing engine that includes the template and stores the output. Drupal's theme engines can provide alternate template engines, such as XTemplate, Smarty and PHPTal. The most common template engine is PHPTemplate (included with Drupal and implemented in phptemplate.engine, which uses Drupal's default template renderer.
In order to create theme-specific implementations of these hooks, themes can implement their own version of theme hooks, either as functions or templates. These implementations will be used instead of the default implementation. If using a pure .theme without an engine, the .theme is required to implement its own version of hook_theme() to tell Drupal what it is implementing; themes utilizing an engine will have their well-named theming functions automatically registered for them. While this can vary based upon the theme engine, the standard set by phptemplate is that theme functions should be named either phptemplate_HOOK or THEMENAME_HOOK. For example, for Drupal's default theme (Garland) to implement the 'table' hook, the phptemplate.engine would find phptemplate_table() or garland_table(). The ENGINE_HOOK() syntax is preferred, as this can be used by sub-themes (which are themes that share code but use different stylesheets).
The theme system is described and defined in theme.inc.
hook_theme()
| acquia_agent_system_modules | ( | $ | form | ) |
Override of the theme callback for the modules form.
Used add extra rows when $form['description][$key]['extra'] is set.
| $form | An associative array containing the structure of the form. |
| phptemplate_menu_local_tasks | ( | ) |
Returns the rendered local tasks. The default implementation renders them as tabs. Overridden to split the secondary tasks.
| phptemplate_uc_cart_block_content | ( | $ | help_text, | |
| $ | items, | |||
| $ | item_count, | |||
| $ | item_text, | |||
| $ | total, | |||
| $ | summary_links | |||
| ) |
Theme the shopping cart block content.
| $help_text | Text to place in the small help text area beneath the cart block title or FALSE if disabled. | |
| $items | An associative array of item information containing the keys 'qty', 'title', 'price', and 'desc'. | |
| $item_count | The number of items in the shopping cart. | |
| $item_text | A textual representation of the number of items in the shopping cart. | |
| $total | The unformatted total of all the products in the shopping cart. | |
| $summary_links | An array of links used in the cart summary. |
| phptemplate_uc_cart_block_items | ( | $ | items | ) |
Theme the table listing the items in the shopping cart block.
| $items | An associative array of item information containing the keys 'qty', 'title', 'price', and 'desc'. |
| phptemplate_uc_cart_block_summary | ( | $ | item_count, | |
| $ | item_text, | |||
| $ | total, | |||
| $ | summary_links | |||
| ) |
Theme the summary table at the bottom of the default shopping cart block.
| $item_count | The number of items in the shopping cart. | |
| $item_text | A textual representation of the number of items in the shopping cart. | |
| $total | The unformatted total of all the products in the shopping cart. | |
| $summary_links | An array of links used in the summary. |
| theme_admin_block | ( | $ | block | ) |
This function formats an administrative block for display.
| $block | An array containing information about the block. It should include a 'title', a 'description' and a formatted 'content'. |
| theme_admin_block_content | ( | $ | content | ) |
This function formats the content of an administrative block.
| $block | An array containing information about the block. It should include a 'title', a 'description' and a formatted 'content'. |
| theme_admin_page | ( | $ | blocks | ) |
This function formats an administrative page for viewing.
| $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'. |
| theme_aggregator_categorize_items | ( | $ | form | ) |
Theme the page list form for assigning categories.
| $form | An associative array containing the structure of the form. |
| theme_aggregator_page_opml | ( | $ | feeds | ) |
Theme the OPML feed output.
| $feeds | An array of the feeds to theme. |
| theme_aggregator_page_rss | ( | $ | feeds, | |
| $ | category = NULL | |||
| ) |
Theme the RSS output.
| $feeds | An array of the feeds to theme. | |
| $category | A common category, if any, for all the feeds. |
| theme_blocks | ( | $ | region | ) |
Return a set of blocks available for the current user.
| $region | Which set of blocks to retrieve. |
| theme_book_admin_table | ( | $ | form | ) |
Theme function for the book administration page form.
| theme_box | ( | $ | title, | |
| $ | content, | |||
| $ | region = 'main' | |||
| ) |
Return a themed box.
| $title | The subject of the box. | |
| $content | The content of the box. | |
| $region | The region in which the box is displayed. |
| theme_breadcrumb | ( | $ | breadcrumb | ) |
Return a themed breadcrumb trail.
| $breadcrumb | An array containing the breadcrumb links. |
| theme_button | ( | $ | element | ) |
Theme a form button.
| theme_cart_review_table | ( | $ | show_subtotal = TRUE |
) |
Format the cart contents table on the checkout page.
| $show_subtotal | TRUE or FALSE indicating if you want a subtotal row displayed in the table. |
| theme_checkbox | ( | $ | element | ) |
Format a checkbox.
| $element | An associative array containing the properties of the element. Properties used: title, value, return_value, description, required |
| theme_checkboxes | ( | $ | element | ) |
Format a set of checkboxes.
| $element | An associative array containing the properties of the element. |
| theme_closure | ( | $ | main = 0 |
) |
Execute hook_footer() which is run at the end of the page right before the close of the body tag.
| $main | (optional) Whether the current page is the front page of the site. |
| theme_comment_admin_overview | ( | $ | form | ) |
Theme the comment admin form.
| $form | An associative array containing the structure of the form. |
| theme_date | ( | $ | element | ) |
Format a date selection element.
| $element | An associative array containing the properties of the element. Properties used: title, value, options, description, required and attributes. |
| theme_feed_icon | ( | $ | url, | |
| $ | title | |||
| ) |
Return code that emits an feed icon.
| $url | The url of the feed. | |
| $title | A descriptive title of the feed. |
| theme_fieldset | ( | $ | element | ) |
Format a group of form items.
| $element | An associative array containing the properties of the element. Properties used: attributes, title, value, description, children, collapsible, collapsed |
| theme_file | ( | $ | element | ) |
Format a file upload field.
| $title | The label for the file upload field. | |
| $name | The internal name used to refer to the field. | |
| $size | A measure of the visible size of the field (passed directly to HTML). | |
| $description | Explanatory text to display after the form item. | |
| $required | Whether the user must upload a file to the field. |
| theme_filter_admin_order | ( | $ | form | ) |
Theme filter order configuration form.
| theme_filter_admin_overview | ( | $ | form | ) |
Theme the admin overview form.
| theme_filter_tips | ( | $ | tips, | |
| $ | long = FALSE, |
|||
| $ | extra = '' | |||
| ) |
Format a set of filter tips.
| theme_form | ( | $ | element | ) |
Format a form.
| $element | An associative array containing the properties of the element. Properties used: action, method, attributes, children |
| theme_form_element | ( | $ | element, | |
| $ | value | |||
| ) |
Return a themed form element.
| element | An associative array containing the properties of the element. Properties used: title, description, id, required | |
| $value | The form element's data. |
| theme_help | ( | ) |
Return a themed help message.
| theme_hidden | ( | $ | element | ) |
Format a hidden form field.
| $element | An associative array containing the properties of the element. Properties used: value, edit |
| theme_image | ( | $ | path, | |
| $ | alt = '', |
|||
| $ | title = '', |
|||
| $ | attributes = NULL, |
|||
| $ | getsize = TRUE | |||
| ) |
Return a themed image.
| $path | Either the path of the image file (relative to base_path()) or a full URL. | |
| $alt | The alternative text for text-based browsers. | |
| $title | The title text is displayed when the image is hovered in some popular browsers. | |
| $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. |
| theme_image_button | ( | $ | element | ) |
Theme a form image button.
| theme_indentation | ( | $ | size = 1 |
) |
Create a standard indentation div. Used for drag and drop tables.
| $size | Optional. The number of indentations to create. |
| theme_item | ( | $ | element | ) |
Format a form item.
| $element | An associative array containing the properties of the element. Properties used: title, value, description, required, error |
| theme_item_list | ( | $ | items = array(), |
|
| $ | title = NULL, |
|||
| $ | type = 'ul', |
|||
| $ | attributes = NULL | |||
| ) |
Return a themed list of items.
| $items | An array of items to be displayed in the list. If an item is a string, then it is used as is. If an item is an array, then the "data" element of the array is used as the contents of the list item. If an item is an array with a "children" element, those children are displayed in a nested list. All other elements are treated as attributes of the list item element. | |
| $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. |
| theme_links | ( | $ | links, | |
| $ | attributes = array('class' => 'links') | |||
| ) |
Return a themed set of links.
| $links | A keyed array of links to be themed. | |
| $attributes | A keyed array of attributes |
| theme_locale_languages_overview_form | ( | $ | form | ) |
Theme the language overview form.
| theme_mark | ( | $ | type = MARK_NEW |
) |
Return a themed marker, useful for marking new or updated content.
| $type | Number representing the marker type to display |
| theme_markup | ( | $ | element | ) |
Format HTML markup for use in forms.
This is used in more advanced forms, such as theme selection and filter format.
| $element | An associative array containing the properties of the element. Properties used: value, children. |
| theme_menu_item | ( | $ | link, | |
| $ | has_children, | |||
| $ | menu = '', |
|||
| $ | in_active_trail = FALSE, |
|||
| $ | extra_class = NULL | |||
| ) |
Generate the HTML output for a menu item and submenu.
| theme_menu_item_link | ( | $ | link | ) |
Generate the HTML output for a single menu link.
| theme_menu_local_task | ( | $ | link, | |
| $ | active = FALSE | |||
| ) |
Generate the HTML output for a single local task link.
| theme_menu_local_tasks | ( | ) |
Returns the rendered local tasks. The default implementation renders them as tabs.
| theme_menu_overview_form | ( | $ | form | ) |
Theme the menu overview form into a table.
| theme_menu_tree | ( | $ | tree | ) |
Generate the HTML output for a menu tree
| theme_more_help_link | ( | $ | url | ) |
Returns code that emits the 'more help'-link.
| theme_more_link | ( | $ | url, | |
| $ | title | |||
| ) |
Returns code that emits the 'more' link used on blocks.
| $url | The url of the main page | |
| $title | A descriptive verb for the link, like 'Read more' |
| theme_node_add_list | ( | $ | content | ) |
Display the list of available node types for node creation.
| theme_node_admin_nodes | ( | $ | form | ) |
Theme node administration overview.
| theme_node_filter_form | ( | $ | form | ) |
Theme node administration filter form.
| theme_node_filters | ( | $ | form | ) |
Theme node administration filter selector.
| theme_node_form | ( | $ | form | ) |
Present a node submission form.
| theme_node_preview | ( | $ | node | ) |
Display a node preview for display during node creation and editing.
| $node | The node object which is being previewed. |
| theme_pager | ( | $ | tags = array(), |
|
| $ | limit = 10, |
|||
| $ | element = 0, |
|||
| $ | parameters = array(), |
|||
| $ | quantity = 9 | |||
| ) |
Format a query pager.
Menu callbacks that display paged query results should call theme('pager') to retrieve a pager control so that users can view other results. Format a list of nearby pages with additional query results.
| $tags | An array of labels for the controls in the pager. | |
| $limit | The number of query results to display per page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $parameters | An associative array of query string parameters to append to the pager links. | |
| $quantity | The number of pages in the list. |
| theme_pager_first | ( | $ | text, | |
| $ | limit, | |||
| $ | element = 0, |
|||
| $ | parameters = array() | |||
| ) |
Format a "first page" link.
| $text | The name (or image) of the link. | |
| $limit | The number of query results to display per page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $parameters | An associative array of query string parameters to append to the pager links. |
| theme_pager_last | ( | $ | text, | |
| $ | limit, | |||
| $ | element = 0, |
|||
| $ | parameters = array() | |||
| ) |
Format a "last page" link.
| $text | The name (or image) of the link. | |
| $limit | The number of query results to display per page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $parameters | An associative array of query string parameters to append to the pager links. |
| theme_pager_link | ( | $ | text, | |
| $ | page_new, | |||
| $ | element, | |||
| $ | parameters = array(), |
|||
| $ | attributes = array() | |||
| ) |
Format a link to a specific query result page.
| $page_new | The first result to display on the linked page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $parameters | An associative array of query string parameters to append to the pager link. | |
| $attributes | An associative array of HTML attributes to apply to a pager anchor tag. |
| theme_pager_next | ( | $ | text, | |
| $ | limit, | |||
| $ | element = 0, |
|||
| $ | interval = 1, |
|||
| $ | parameters = array() | |||
| ) |
Format a "next page" link.
| $text | The name (or image) of the link. | |
| $limit | The number of query results to display per page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $interval | The number of pages to move forward when the link is clicked. | |
| $parameters | An associative array of query string parameters to append to the pager links. |
| theme_pager_previous | ( | $ | text, | |
| $ | limit, | |||
| $ | element = 0, |
|||
| $ | interval = 1, |
|||
| $ | parameters = array() | |||
| ) |
Format a "previous page" link.
| $text | The name (or image) of the link. | |
| $limit | The number of query results to display per page. | |
| $element | An optional integer to distinguish between multiple pagers on one page. | |
| $interval | The number of pages to move backward when the link is clicked. | |
| $parameters | An associative array of query string parameters to append to the pager links. |
| theme_password | ( | $ | element | ) |
Format a password field.
| $element | An associative array containing the properties of the element. Properties used: title, value, description, size, maxlength, required, attributes |
| theme_password_confirm | ( | $ | element | ) |
Format a password_confirm item.
| $element | An associative array containing the properties of the element. Properties used: title, value, id, required, error. |
| theme_placeholder | ( | $ | text | ) |
Formats text for emphasized display in a placeholder inside a sentence. Used automatically by t().
| $text | The text to format (plain-text). |
| theme_profile_admin_overview | ( | $ | form | ) |
Theme the profile field overview into a drag and drop enabled table.
| theme_progress_bar | ( | $ | percent, | |
| $ | message | |||
| ) |
Return a themed progress bar.
| $percent | The percentage of the progress. | |
| $message | A string containing information to be displayed. |
| theme_radio | ( | $ | element | ) |
Format a radio button.
| $element | An associative array containing the properties of the element. Properties used: required, return_value, value, attributes, title, description |
| theme_radios | ( | $ | element | ) |
Format a set of radio buttons.
| $element | An associative array containing the properties of the element. Properties used: title, value, options, description, required and attributes. |
| theme_select | ( | $ | element | ) |
Format a dropdown menu or scrolling selection box.
| $element | An associative array containing the properties of the element. Properties used: title, value, options, description, extra, multiple, required |
| theme_status_messages | ( | $ | display = NULL |
) |
Return a themed set of status and/or error messages. The messages are grouped by type.
| $display | (optional) Set to 'status' or 'error' to display only messages of that type. |
| theme_status_report | ( | &$ | requirements | ) |
Theme requirements status report.
| $requirements | An array of requirements. |
| theme_submenu | ( | $ | links | ) |
Return a themed submenu, typically displayed under the tabs.
| $links | An array of links. |
| theme_submit | ( | $ | element | ) |
Theme a form submit button.
| theme_summary_overview | ( | $ | summaries, | |
| $ | link = TRUE | |||
| ) |
Themes a summaries array into a handy div for use with some JS enhancement.
| $summaries | An array of summary arrays each containing the following keys:
| |
| $link | TRUE or FALSE indicating whether or not to display an edit icon linking to the settings form the summary represents. |
| theme_system_admin_by_module | ( | $ | menu_items | ) |
Theme output of the dashboard page.
| $menu_items | An array of modules to be displayed. |
| theme_system_modules | ( | $ | form | ) |
Theme callback for the modules form.
| $form | An associative array containing the structure of the form. |
| theme_system_modules_uninstall | ( | $ | form | ) |
Themes a table of currently disabled modules.
| $form | The form array representing the currently disabled modules. |
| theme_system_theme_select_form | ( | $ | form | ) |
Theme the theme select form.
| $form | An associative array containing the structure of the form. |
| theme_system_themes_form | ( | $ | form | ) |
Theme function for the system themes form.
| $form | An associative array containing the structure of the form. |
| theme_table | ( | $ | header, | |
| $ | rows, | |||
| $ | attributes = array(), |
|||
| $ | caption = NULL | |||
| ) |
Return a themed table.
| $header | An array containing the table headers. Each element of the array can be either a localized string or an associative array with the following keys:
| |
| $rows | An array of table rows. Every row is an array of cells, or an associative array with the following keys:
|
Here's an example for $rows:
* $rows = array(
* // Simple row
* array(
* 'Cell 1', 'Cell 2', 'Cell 3'
* ),
* // Row with attributes on the row and some of its cells.
* array(
* 'data' => array('Cell 1', array('data' => 'Cell 2', 'colspan' => 2)), 'class' => 'funky'
* )
* );
*
| $attributes | An array of HTML attributes to apply to the table tag. | |
| $caption | A localized string to use for the tag. |
| theme_table_select_header_cell | ( | ) |
Returns a header cell for tables that have a select all functionality.
| theme_tablesort_indicator | ( | $ | style | ) |
Return a themed sort icon.
| $style | Set to either asc or desc. This sets which icon to show. |
| theme_tapir_table | ( | $ | element | ) |
Themes form data into a table for display.
| $form | The array of form information needing to be rendered into the table. |
| theme_task_list | ( | $ | items, | |
| $ | active = NULL | |||
| ) |
Return a themed list of maintenance tasks to perform.
| theme_taxonomy_overview_terms | ( | $ | form | ) |
| theme_taxonomy_overview_vocabularies | ( | $ | form | ) |
Theme the vocabulary overview as a sortable list of vocabularies.
| theme_taxonomy_term_page | ( | $ | tids, | |
| $ | result | |||
| ) |
Render a taxonomy term page HTML output.
| $tids | An array of term ids. | |
| $result | A pager_query() result, such as that performed by taxonomy_select_nodes(). |
| theme_textarea | ( | $ | element | ) |
Format a textarea.
| $element | An associative array containing the properties of the element. Properties used: title, value, description, rows, cols, required, attributes |
| theme_textfield | ( | $ | element | ) |
Format a textfield.
| $element | An associative array containing the properties of the element. Properties used: title, value, description, size, maxlength, required, attributes autocomplete_path |
| theme_token | ( | $ | element | ) |
Format a form token.
| theme_trigger_display | ( | $ | element | ) |
Display actions assigned to this hook-op combination in a table.
| array | $element The fieldset including all assigned actions. |
| theme_uc_attribute_options_form | ( | $ | form | ) |
Format an attribute and its options.
| theme_uc_cart_checkout_review | ( | $ | panes, | |
| $ | form | |||
| ) |
Theme the checkout review order page.
| $panes | An associative array for each checkout pane that has information to add to the review page. The key is the pane's title and the value is either the data returned for that pane or an array of returned data. | |
| $form | The HTML version of the form that by default includes the 'Back' and 'Submit order' buttons at the bottom of the review page. |
| theme_uc_object_attributes_form | ( | $ | form | ) |
Display the formatted attribute form.
| theme_uc_object_options_form | ( | $ | form | ) |
Display the option form.
| theme_uc_price_settings_form | ( | $ | form | ) |
Render the price handler form, adding tabledrag.
| theme_uc_product_field_settings_form | ( | $ | form | ) |
| theme_uc_quote_method_settings | ( | $ | form | ) |
Display a formatted list of shipping quote methods and form elements.
| theme_uc_shipping_edit_package_fieldset | ( | $ | fieldset | ) |
Display a formatted shipping type fieldset.
| theme_uc_shipping_new_package_fieldset | ( | $ | fieldset | ) |
Format and display the products in a shipping type fieldset.
| theme_uc_shipping_new_shipment | ( | $ | form | ) |
Format and display the new shipment form.
| theme_uc_ups_label_image | ( | ) |
Display the shipping label for printing.
Each argument is a component of the file path to the image.
| theme_uc_ups_option_label | ( | $ | service | ) |
Theme function to format the UPS service name and rate amount line-item shown to the customer.
| $service | The UPS service name. |
| theme_update_report | ( | $ | data | ) |
Theme project status report.
| theme_update_version | ( | $ | version, | |
| $ | tag, | |||
| $ | class | |||
| ) |
Theme the version display of a project.
| theme_user_admin_account | ( | $ | form | ) |
Theme user administration overview.
| theme_user_admin_new_role | ( | $ | form | ) |
Theme the new-role form.
| theme_user_admin_perm | ( | $ | form | ) |
Theme the administer permissions page.
| theme_user_filter_form | ( | $ | form | ) |
Theme user administration filter form.
| theme_user_filters | ( | $ | form | ) |
Theme user administration filter selector.
| theme_username | ( | $ | object | ) |
Format a username.
| $object | The user object to format, usually returned from user_load(). |
| theme_xml_icon | ( | $ | url | ) |
Return code that emits an XML icon.
For most use cases, this function has been superseded by theme_feed_icon().
| $url | The url of the feed. |