Generates the themed output.

Generates the themed output.

All requests for theme hooks must go through this function. It examines the request and routes it to the appropriate theme function. The theme registry is checked to determine which implementation to use, which may be a function or a template.

If the implementation is a function, it is executed and its return value passed along.

If the implementation is a template, the arguments are converted to a $variables array. This array is then modified by the module implementing the hook, theme engine (if applicable) and the theme. The following functions may be used to modify the $variables array. They are processed in this order when available:

  • template_preprocess(&$variables, $hook) This sets a default set of variables for all template implementations.
  • template_preprocess_HOOK(&$variables) This is the first preprocessor called specific to the hook; it should be implemented by the module that registers it.
  • MODULE_preprocess(&$variables, $hook) This will be called for all templates; it should only be used if there is a real need. It's purpose is similar to template_preprocess().
  • MODULE_preprocess_HOOK(&$variables) This is for modules that want to alter or provide extra variables for theming hooks not registered to itself. For example, if a module named "foo" wanted to alter the $submitted variable for the hook "node" a preprocess function of foo_preprocess_node() can be created to intercept and alter the variable.
  • ENGINE_engine_preprocess(&$variables, $hook) This function should only be implemented by theme engines and exists so that it can set necessary variables for all hooks.
  • ENGINE_engine_preprocess_HOOK(&$variables) This is the same as the previous function, but it is called for a single theming hook.
  • ENGINE_preprocess(&$variables, $hook) This is meant to be used by themes that utilize a theme engine. It is provided so that the preprocessor is not locked into a specific theme. This makes it easy to share and transport code but theme authors must be careful to prevent fatal re-declaration errors when using sub-themes that have their own preprocessor named exactly the same as its base theme. In the default theme engine (PHPTemplate), sub-themes will load their own template.php file in addition to the one used for its parent theme. This increases the risk for these errors. A good practice is to use the engine name for the base theme and the theme name for the sub-themes to minimize this possibility.
  • ENGINE_preprocess_HOOK(&$variables) The same applies from the previous function, but it is called for a specific hook.
  • THEME_preprocess(&$variables, $hook) These functions are based upon the raw theme; they should primarily be used by themes that do not use an engine or by sub-themes. It serves the same purpose as ENGINE_preprocess().
  • THEME_preprocess_HOOK(&$variables) The same applies from the previous function, but it is called for a specific hook.

There are two special variables that these hooks can set: 'template_file' and 'template_files'. These will be merged together to form a list of 'suggested' alternate template files to use, in reverse order of priority. template_file will always be a higher priority than items in template_files. theme() will then look for these files, one at a time, and use the first one that exists.


joshmiller’s picture

This documentation makes no sense to me ;P

The docs book page on the theme registry and how to use it has illustrations and MAKES SENSE:


and of particular interest is this AMAZING pdf that explained this whole thing in about 10 seconds:


Also... it turns out I was actually looking to implement a hook for the theme function and that means you have tell drupal about this hook using hook_theme() ... who knew?

armanschwarz’s picture

This is terrible. I was less confused before I read that. Drupal documentation isn't the best but this needs some serious revision.

pcher1bw’s picture

Try reading Pro Drupal Development by John K. VanDyk, Chapter 3 discusses Hooks, Triggers and Actions, Chapter 2 describes how to write a module. MODULE_ above refers to your module name, for example if your module name is annotate then annotate_theme() is the hook for the theme for the annotate module.

mattjbondi’s picture

Thank goodness......... I thought I was the only one who was struggling with Drupal documentation. It is so relieving to have others to commiserate with. Thanks for the tip on Pro Drupal Development.

Diogenes’s picture

So I looked at this page again, because I manage both D6 & D7 sites. I agree - this page is confusing.

At the very top of the page are two different function prototypes. I'm using C programming terminology here; bear with me, I'm getting old. To express this in old fashioned C style, the prototypes would be more like:

Drupal 4.6-6 theme( ... )
Drupal 7-8 theme( hook, ... )

The ... in the prototypes above mean a variable argument list. It could be a PHP associative list, it could be an object with the grand unifying theory of the universe embedded within.

In any event, the function using the ... parameter must have knowledge of the context to behave differently from the default behavior if the ... parameter is used.

So theme(...) is always passed an argument, though it elegantly defaults if no arguments are passed. In most situations there are arguments. The first one should always be the hook name. The theme() function has all kind of ways to derive and overide,

So both prototypes above are really expressing the same thing. It's a variable argument list.

There are remarkable ways of theming output with Drupal and the code included above gives to clues as to how it's all possible.

Don't worry if the included code doesn't make sense right now. Read more about hooks and templates first, and then visit here again.

Botros’s picture

I need to theme the user profile, what can i do ?
can i do something like that
theme('user_profile', $account);
is user_profile is a hook?

johnnydarkko’s picture

'user_profile' is the name of the theme hook function you'll need to use to override the default output. So to override this, you can copy the theme_user_profile() function to your theme's template.php and override the output. Change the function name to {YOUR_THEME_NAME}_user_profile().

Hope that helps!

mottolini’s picture

Hope this could help someone else.

If you have a hook_theme like this:

function yourmodule_theme() {
  return array(
    'xxx_yyy_zzz' => array(
      'arguments' => array(
        'arg1' => NULL, 
        'arg2' => NULL, 
      'template' => 'any_name_here', 

You'll probably find out that the template file used to render this theme function will always be the one provided by your module in /sites/all/modules/yourmodule/any_name_here.tpl.php. Any file named any_name_here.tpl.php put in any theme will simply be ignored, regardless of how many time your clear the cache or install and deinstall module and themes.

What you have to do is simply to name your template exactly like your function and not "any_name_here". So your hook_theme has to be:

function yourmodule_theme() {
  return array(
    'xxx_yyy_zzz' => array(
      'arguments' => array(
        'arg1' => NULL, 
        'arg2' => NULL, 
      'template' => 'xxx-yyy-zzz', 

You can use 'xxx-yyy-zzz' even if the function uses underscores instead of hyphens, because Drupal translates one into the other in core when it has to match functions and templates.
Of course your template file in the module and in the theme has to be named xxx-yyy-zzz.tpl.php.