function hook_theme

Same name in other branches
  1. 9 core/lib/Drupal/Core/Render/theme.api.php \hook_theme()
  2. 8.9.x core/lib/Drupal/Core/Render/theme.api.php \hook_theme()
  3. 10 core/lib/Drupal/Core/Render/theme.api.php \hook_theme()
  4. 11.x core/lib/Drupal/Core/Render/theme.api.php \hook_theme()

Register a module (or theme's) theme implementations.

The implementations declared by this hook have two purposes: either they specify how a particular render array is to be rendered as HTML (this is usually the case if the theme function is assigned to the render array's #theme property), or they return the HTML that should be returned by an invocation of theme(). See Using the theme layer Drupal 7.x for more information on how to implement theme hooks.

The following parameters are all optional.

Parameters

array $existing: An array of existing implementations that may be used for override purposes. This is primarily useful for themes that may wish to examine existing implementations to extract data (such as arguments) so that it may properly register its own, higher priority implementations.

$type: Whether a theme, module, etc. is being processed. This is primarily useful so that themes tell if they are the actual theme being called or a parent theme. May be one of:

  • 'module': A module is being checked for theme implementations.
  • 'base_theme_engine': A theme engine is being checked for a theme that is a parent of the actual theme being used.
  • 'theme_engine': A theme engine is being checked for the actual theme being used.
  • 'base_theme': A base theme is being checked for theme implementations.
  • 'theme': The actual theme in use is being checked.

$theme: The actual name of theme, module, etc. that is being being processed.

$path: The directory path of the theme or module, so that it doesn't need to be looked up.

Return value

array An associative array of theme hook information. The keys on the outer array are the internal names of the hooks, and the values are arrays containing information about the hook. Each information array must contain either a 'variables' element or a 'render element' element, but not both. Use 'render element' if you are theming a single element or element tree composed of elements, such as a form array, a page array, or a single checkbox element. Use 'variables' if your theme implementation is intended to be called directly through theme() and has multiple arguments for the data and style; in this case, the variables not supplied by the calling function will be given default values and passed to the template or theme function. The returned theme information array can contain the following key/value pairs:

  • variables: (see above) Each array key is the name of the variable, and the value given is used as the default value if the function calling theme() does not supply it. Template implementations receive each array key as a variable in the template file (so they must be legal PHP variable names). Function implementations are passed the variables in a single $variables function argument.
  • render element: (see above) The name of the renderable element or element tree to pass to the theme function. This name is used as the name of the variable that holds the renderable element or tree in preprocess and process functions.
  • file: The file the implementation resides in. This file will be included prior to the theme being rendered, to make sure that the function or preprocess function (as needed) is actually loaded; this makes it possible to split theme functions out into separate files quite easily.
  • path: Override the path of the file to be used. Ordinarily the module or theme path will be used, but if the file will not be in the default path, include it here. This path should be relative to the Drupal root directory.
  • template: If specified, this theme implementation is a template, and this is the template file without an extension. Do not put .tpl.php on this file; that extension will be added automatically by the default rendering engine (which is PHPTemplate). If 'path', above, is specified, the template should also be in this path.
  • function: If specified, this will be the function name to invoke for this implementation. If neither 'template' nor 'function' is specified, a default function name will be assumed. For example, if a module registers the 'node' theme hook, 'theme_node' will be assigned to its function. If the chameleon theme registers the node hook, it will be assigned 'chameleon_node' as its function.
  • base hook: A string declaring the base theme hook if this theme implementation is actually implementing a suggestion for another theme hook.
  • pattern: A regular expression pattern to be used to allow this theme implementation to have a dynamic name. The convention is to use __ to differentiate the dynamic portion of the theme. For example, to allow forums to be themed individually, the pattern might be: 'forum__'. Then, when the forum is themed, call: 
theme(array(
    'forum__' . $tid,
    'forum',
), $forum);
  • preprocess functions: A list of functions used to preprocess this data. Ordinarily this won't be used; it's automatically filled in. By default, for a module this will be filled in as template_preprocess_HOOK. For a theme this will be filled in as phptemplate_preprocess and phptemplate_preprocess_HOOK as well as themename_preprocess and themename_preprocess_HOOK.
  • override preprocess functions: Set to TRUE when a theme does NOT want the standard preprocess functions to run. This can be used to give a theme FULL control over how variables are set. For example, if a theme wants total control over how certain variables in the page.tpl.php are set, this can be set to true. Please keep in mind that when this is used by a theme, that theme becomes responsible for making sure necessary variables are set.
  • type: (automatically derived) Where the theme hook is defined: 'module', 'theme_engine', or 'theme'.
  • theme path: (automatically derived) The directory path of the theme or module, so that it doesn't need to be looked up.

See also

hook_theme_registry_alter()

Related topics

Hooks
Allow modules to interact with the Drupal core.
42 functions implement hook_theme()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_theme in modules/aggregator/aggregator.module
Implements hook_theme().
ajax_base_page_theme in includes/ajax.inc
Theme callback for Ajax requests.
block_theme in modules/block/block.module
Implements hook_theme().
book_theme in modules/book/book.module
Implements hook_theme().
color_theme in modules/color/color.module
Implements hook_theme().

... See full list

1 invocation of hook_theme()
_theme_build_registry in includes/theme.inc
Builds the theme registry cache.

File

modules/system/system.api.php, line 2304

Code

function hook_theme($existing, $type, $theme, $path) {
    return array(
        'forum_display' => array(
            'variables' => array(
                'forums' => NULL,
                'topics' => NULL,
                'parents' => NULL,
                'tid' => NULL,
                'sortby' => NULL,
                'forum_per_page' => NULL,
            ),
        ),
        'forum_list' => array(
            'variables' => array(
                'forums' => NULL,
                'parents' => NULL,
                'tid' => NULL,
            ),
        ),
        'forum_topic_list' => array(
            'variables' => array(
                'tid' => NULL,
                'topics' => NULL,
                'sortby' => NULL,
                'forum_per_page' => NULL,
            ),
        ),
        'forum_icon' => array(
            'variables' => array(
                'new_posts' => NULL,
                'num_posts' => 0,
                'comment_mode' => 0,
                'sticky' => 0,
            ),
        ),
        'status_report' => array(
            'render element' => 'requirements',
            'file' => 'system.admin.inc',
        ),
        'system_date_time_settings' => array(
            'render element' => 'form',
            'file' => 'system.admin.inc',
        ),
    );
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.