\themeable
group
Functions and templates for the user interface to be implemented by themes.

Functions and templates for the user interface to be implemented by themes.

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 an array of variables. For example, theme('table', array('header' => $header, 'rows' => $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'), $variables) 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 THEMENAME_HOOK. For example, for Drupal's default theme (Bartik) to implement the 'table' hook, the phptemplate.engine would find bartik_table().

The theme system is described and defined in theme.inc.

End of "defgroup themeable".

Comments

Sheldon Rampton’s picture

This page currently lists two separate functions with the identical name "theme_field," one of which says it is "Implemented using the field.tpl.php template," and one which says it "Returns HTML for a field." This is rathe confusing.

When I click through to the first "theme_field" link, it takes me to a function which simply contains a comment that says, "This function is never used; see the corresponding template file instead." However, clicking through to http://api.drupal.org/api/drupal/modules--field--theme--field.tpl.php/7 takes me to a page which says, "This file is not used and is here as a starting point for customization only."

Clicking through to the second "theme_field" link at http://api.drupal.org/api/drupal/modules--field--field.module/function/t... takes me to more helpful documentation which explains that
field.tpl.php can be found in the "modules/field/theme" directory. By reading the two theme_field links against each other, it is possible to figure things out. However, having two separate links is somewhat confusing, and it would be nice if this could be fixed.

petabyte’s picture

Even though I believe that you answered that question by yourself in the meantime, I want to answer it for all future visitors:

You can control the rendering output of a field either by using a (custom) field.tpl.php file or by implementing a custom field theme function. Both ways exist in parallel. The latter is more efficient (in terms of computational resources) and offers greater flexibility (f.e. access to data not exposed to a tpl file).

"This function is never used; see the corresponding template file instead." <-- is kind of dummy/placeholder value.

mavaddat’s picture

Are these paragraphs not saying the same thing twice?

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.

paulwdru’s picture

I have to read through many documents from different sources in order to know the exact behaviors of theme(), theme hook, theme function and theme template, the help file is quite misleading with contradiction, initially saying A > B but then A = B in later statements.

KimMyungSik’s picture

Nice Drupal Thanks