\theme
function
Generates themed output.

Generates themed output.

All requests for themed output must go through this function (however, calling the theme() function directly is strongly discouraged - see next paragraph). It examines the request and routes it to the appropriate @link themeable theme function or template @endlink, by checking the theme registry.

Avoid calling this function directly. It is preferable to replace direct calls to the theme() function with calls to drupal_render() by passing a render array with a #theme key to drupal_render(), which in turn calls theme().

Theme Hooks

Most commonly, the first argument to this function is the name of the theme hook. For instance, to theme a taxonomy term, the theme hook name is 'taxonomy_term'. Modules register theme hooks within a hook_theme() implementation and provide a default implementation via a function named theme_HOOK() (e.g., theme_taxonomy_term()) or via a template file named according to the value of the 'template' key registered with the theme hook (see hook_theme() for details). Default templates are implemented with the PHPTemplate rendering engine and are named the same as the theme hook, with underscores changed to hyphens, so for the 'taxonomy_term' theme hook, the default template is 'taxonomy-term.tpl.php'.

Overriding Theme Hooks

Themes may also register new theme hooks within a hook_theme() implementation, but it is more common for themes to override default implementations provided by modules than to register entirely new theme hooks. Themes can override a default implementation by implementing a function named THEME_HOOK() (for example, the 'bartik' theme overrides the default implementation of the 'menu_tree' theme hook by implementing a bartik_menu_tree() function), or by adding a template file within its folder structure that follows the template naming structure used by the theme's rendering engine (for example, since the Bartik theme uses the PHPTemplate rendering engine, it overrides the default implementation of the 'page' theme hook by containing a 'page.tpl.php' file within its folder structure).

Preprocessing for Template Files

If the implementation is a template file, several functions are called before the template file is invoked, to modify the $variables array. These fall into the "preprocessing" phase and the "processing" phase, and are executed (if they exist), in the following order (note that in the following list, HOOK indicates the theme hook name, MODULE indicates a module name, THEME indicates a theme name, and ENGINE indicates a theme engine name):

  • template_preprocess(&$variables, $hook): Creates a default set of variables for all theme hooks with template implementations.
  • template_preprocess_HOOK(&$variables): Should be implemented by the module that registers the theme hook, to set up default variables.
  • MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all implementing modules.
  • MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on all implementing modules, so that modules that didn't define the theme hook can alter the variables.
  • ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to set necessary variables for all theme hooks with template implementations.
  • ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set necessary variables for the particular theme hook.
  • THEME_preprocess(&$variables, $hook): Allows the theme to set necessary variables for all theme hooks with template implementations.
  • THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary variables specific to the particular theme hook.
  • template_process(&$variables, $hook): Creates an additional set of default variables for all theme hooks with template implementations. The variables created in this function are derived from ones created by template_preprocess(), but potentially altered by the other preprocess functions listed above. For example, any preprocess function can add to or modify the $variables['attributes_array'] variable, and after all of them have finished executing, template_process() flattens it into a $variables['attributes'] string for convenient use by templates.
  • template_process_HOOK(&$variables): Should be implemented by the module that registers the theme hook, if it needs to perform additional variable processing after all preprocess functions have finished.
  • MODULE_process(&$variables, $hook): hook_process() is invoked on all implementing modules.
  • MODULE_process_HOOK(&$variables): hook_process_HOOK() is invoked on on all implementing modules, so that modules that didn't define the theme hook can alter the variables.
  • ENGINE_engine_process(&$variables, $hook): Allows the theme engine to process variables for all theme hooks with template implementations.
  • ENGINE_engine_process_HOOK(&$variables): Allows the theme engine to process the variables specific to the theme hook.
  • THEME_process(&$variables, $hook): Allows the theme to process the variables for all theme hooks with template implementations.
  • THEME_process_HOOK(&$variables): Allows the theme to process the variables specific to the theme hook.

Preprocessing for Theme Functions

If the implementation is a function, only the theme-hook-specific preprocess and process functions (the ones ending in _HOOK) are called from the list above. This is because theme hooks with function implementations need to be fast, and calling the non-theme-hook-specific preprocess and process functions for them would incur a noticeable performance penalty.

Suggesting Alternate Hooks

There are two special variables that these preprocess and process functions can set: 'theme_hook_suggestion' and 'theme_hook_suggestions'. These will be merged together to form a list of 'suggested' alternate theme hooks to use, in reverse order of priority. theme_hook_suggestion will always be a higher priority than items in theme_hook_suggestions. theme() will use the highest priority implementation that exists. If none exists, theme() will use the implementation for the theme hook it was called with. These suggestions are similar to and are used for similar reasons as calling theme() with an array as the $hook parameter (see below). The difference is whether the suggestions are determined by the code that calls theme() or by a preprocess or process function.

Comments

benjifisher’s picture

There are two ways to specify a choice of hooks: using double underscores in the hook name, or by passing an array of hook names. Looking at the code, I think you are not expected to do both. For example, if you call theme($hook, $variables) where

 $hook = array('links__mysite__node', 'links__foo__node');

then theme() will check the theme registry for the following hooks:

  1. links__mysite__node
  2. links__foo__node
  3. links__foo
  4. links

but it will never check for links__mysite.

juampynr’s picture

attributes is a reserved variable name that gets set on template_process() (see above for this function). So the following theme definition won't work (ie. the variable won't have the value you set to it):

mymodule_theme() {
  return array(
    'foo' => array(
      'template' => 'some-template',
      'variables' => array('attributes' => ''),
    ),
  );
}

Solution: do not use attributes as a variable within your theme implementation.

rhuffstedtler’s picture

Instead call render() which is a nice wrapper function that will protect you in the case where the argument is just a flat variable rather than a render array().

mchar’s picture

This is how I used theme() to print a message inside a block:

theme('status_messages', drupal_set_message(t('No searches yet! Be the first to search this site'), 'status'));