Community Documentation

hook_theme

6 core.php hook_theme($existing, $type, $theme, $path)
7 system.api.php hook_theme($existing, $type, $theme, $path)
8 system.api.php hook_theme($existing, $type, $theme, $path)

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().

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.
  • 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:

<?php
    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.

Related topics

▾ 56 functions implement hook_theme()

aggregator_theme in modules/aggregator/aggregator.module
Implements hook_theme().
ajax_base_page_theme in includes/ajax.inc
Theme callback for Ajax requests.
BatchPageTestCase::testBatchProgressPageTheme in modules/simpletest/tests/batch.test
Tests that the batch API progress page uses the correct theme.
BlockAdminThemeTestCase::testAdminTheme in modules/block/block.test
Check for the accessibility of the admin theme on the block admin page.
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().
comment_theme in modules/comment/comment.module
Implements hook_theme().
common_test_theme in modules/simpletest/tests/common_test.module
Implements hook_theme().
CSS_THEME in includes/common.inc
The default group for theme CSS files added to the page.
dashboard_theme in modules/dashboard/dashboard.module
Implements hook_theme().
dblog_theme in modules/dblog/dblog.module
Implements hook_theme().
drupal_common_theme in includes/common.inc
Provides theme registration for themes across .inc files.
drupal_maintenance_theme in includes/bootstrap.inc
Enables use of the theme system without requiring database access.
field_theme in modules/field/field.module
Implements hook_theme().
field_ui_theme in modules/field_ui/field_ui.module
Implements hook_theme().
file_theme in modules/file/file.module
Implements hook_theme().
filter_theme in modules/filter/filter.module
Implements hook_theme().
forum_theme in modules/forum/forum.module
Implements hook_theme().
hook_custom_theme in modules/system/system.api.php
Return the machine-readable name of the theme to use for the current page.
image_theme in modules/image/image.module
Implements hook_theme().
JS_THEME in includes/common.inc
The default group for theme JavaScript code added to the page.
locale_theme in modules/locale/locale.module
Implements hook_theme().
MenuRouterTestCase::testHookCustomTheme in modules/simpletest/tests/menu.test
Test that hook_custom_theme() can control the theme of a page.
MenuRouterTestCase::testThemeCallbackFakeTheme in modules/simpletest/tests/menu.test
Test the theme callback when it is set to use a theme that does not exist.
MenuRouterTestCase::testThemeCallbackHookCustomTheme in modules/simpletest/tests/menu.test
Test that the theme callback wins out over hook_custom_theme().
MenuRouterTestCase::testThemeCallbackOptionalTheme in modules/simpletest/tests/menu.test
Test the theme callback when it is set to use an optional theme.
menu_get_custom_theme in includes/menu.inc
Gets the custom theme for the current page, if there is one.
menu_set_custom_theme in includes/menu.inc
Sets a custom theme for the current page, if there is one.
menu_test_custom_theme in modules/simpletest/tests/menu_test.module
Implement hook_custom_theme().
menu_theme in modules/menu/menu.module
Implements hook_theme().
node_theme in modules/node/node.module
Implements hook_theme().
options_theme in modules/field/modules/options/options.module
Implements hook_theme().
overlay_theme in modules/overlay/overlay.module
Implements hook_theme().
path_to_theme in includes/theme.inc
Return the path to the current themed element.
phptemplate_theme in themes/engines/phptemplate/phptemplate.engine
Implements hook_theme().
poll_theme in modules/poll/poll.module
Implements hook_theme().
profile_theme in modules/profile/profile.module
Implements hook_theme().
rdf_theme in modules/rdf/rdf.module
Implements hook_theme().
search_theme in modules/search/search.module
Implements hook_theme().
shortcut_theme in modules/shortcut/shortcut.module
Implements hook_theme().
simpletest_theme in modules/simpletest/simpletest.module
Implements hook_theme().
SystemThemeFunctionalTest::testAdministrationTheme in modules/system/system.test
Test the administration theme functionality.
SystemThemeFunctionalTest::testSwitchDefaultTheme in modules/system/system.test
Test switching the default theme.
system_custom_theme in modules/system/system.module
Implements hook_custom_theme().
system_theme in modules/system/system.module
Implements hook_theme().
taxonomy_theme in modules/taxonomy/taxonomy.module
Implements hook_theme().
theme_test_theme in modules/simpletest/tests/theme_test.module
Implements hook_theme().
toolbar_theme in modules/toolbar/toolbar.module
Implements hook_theme().
trigger_theme in modules/trigger/trigger.module
Implements hook_theme().
update_theme in modules/update/update.module
Implements hook_theme().
user_theme in modules/user/user.module
Implements hook_theme().
_block_custom_theme in modules/block/block.module
Theme callback for the block configuration pages.
_drupal_maintenance_theme in includes/theme.maintenance.inc
Sets up the theming system for maintenance page.
_system_batch_theme in modules/system/system.module
Theme callback for the default batch page.
_theme_custom_theme in modules/simpletest/tests/theme_test.module
Custom theme callback.

File

modules/system/system.api.php, line 2155
Hooks provided by Drupal core and the System module.

Code

<?php
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',
    ),
  );
}
?>

Comments

See also the corresponding alter function

"variables" is used only in D7

This documentation appear to be valid for versions 6 and 7, but in Drupal 6, "arguments" it's used instead of "variables".

hook_theme() in Drupal 6.

hook_theme() in Drupal 6.

Just in case it's not

Just in case it's not completely obvious to those implementing hook_theme in Drupal 7, the custom theme function is passed an array of associative elements. Take for example the following callback function passing the node object:

function custom_output_callback($node) {
  print theme('custom_output', array('node' => $node));
}

function custom_theme() {
  return array(
    'custom_output' => array(
      'variables' => array('node' => NULL),
    ),
  );
}

function theme_custom_output($variables) {
  $node = $variables['node'];
  $build = node_view($node);
  $output = drupal_render($build);
  return $output;
}

The function theme_custom_output() includes the array argument $variables, which contains the node object accessed with the key "node" defined in custom_theme().

I wasted some time figuring out this subtle, but vital difference between Drupal 6 and 7.

Template property

Don't get burned by the descriptions above about template and pattern. They are not as flexible as they are made out to be.

When you override a template, even if the template property is set, the template must match the theme function key (or hook). This essentially makes the template property useless.

'template' property useless?

@mradcliffe

I ran into this same problem. It's very surprising. Is there something we're missing, or is the template property actually just a redundant, useless setting?

_

A fix for this is available for D8 and D7 at http://drupal.org/node/342350. It's been committed for D8, but not yet D7.

If 'template' => 'some-template' doesn't work in D7

If you happen to have same name for a module and a theme don't forget to check the type in hook_theme, because otherwise it may hit 'theme' type and try to include file mymodule-template.tpl.php from the theme's folder instead of the module's folder
Hook theme:

function mymodule_theme($existing, $type, $theme, $path)
{
  if($type == 'module')
  {
    return array(
      'mymodule_template' => array(
        'variables' => array('var_name'=>NULL),
        'template' => 'mymodule-template'
      ),
    );
  }
  return array(); //will raise fatal error if void
}

Call it as usual:

theme('mymodule_template', array('var_name'=>mymodule_variable()));

that's right thank

that's right thank

You should never name your

You should never name your module and theme the same. You may have found a workaround for hook_theme but there are many other places where it will cause confusion. Everything must be unique to prevent naming collisions. This includes theme engines if anyone thinks of writing one. Possibly other types of components too.

Render Elements

The documentation says "render element: (required if "variables" not present) A string that is the name of the sole renderable element to pass to the theme function. The string represents the name of the "variable" that will hold the renderable array inside any optional preprocess or process functions."

It would be better to clarify that $variables can contain a single key whose value is a render array.

To set this up, 'render element' in hook_theme() should hold the name of the key in $variables whose value is the render element. Thus 'render element' => 'myElement' in hook_theme() means that $variables['myElement'] is the render element (or array).

This $variables, with its single key-value pair, is passed to the [pre]process functions and thence to the theme function or template.

See the video http://chicago2011.drupal.org/sessions/render-api-drupal-7 , time 8:00 to 13:30 .

Process functions...

Shouldn't there be a key/value pair for process functions like there is for preprocess functions?

Login or register to post comments