Preprocess functions
Preprocess functions only apply to theming hooks implemented as templates. The main role of the preprocessor is to setup variables to be placed within the template (.tpl.php) files. Plain theme functions do not interact with preprocessors.
Notes:
- Preprocessors are also used for providing template suggestions.
- In versions 5 and below, the function _phptemplate_variables served the same purpose. It has been deprecated in 6.
There can be numerous preprocessors for each theming hook. Every layer from core, modules, engines and themes can have one, each progressively building upon the variables before being rendered through template files. This keeps the markup clean and easy to work with inside templates by placing most of the logic inside these preprocessors.
Here are the expected preprocessors. They are run in this order when they exist:
-
template_preprocess
- This is supplied by core and always added. The variables generated here are used for every templated hook. -
template_preprocess_hook
- The module or core file that implements the theming hook supplies this. The initial generation of all the variables specific to the hook is usually done here. -
moduleName_preprocess
- Do not confuse this with the preprocessor before it. This allows modules that did not originally implement the hook to influence the variables. This would run for all hooks. -
moduleName_preprocess_hook
- Same idea as the previous preprocessor but for specific hooks. -
engineName_engine_preprocess
- The preprocessor for theming engines. Applies to all hooks. -
engineName_engine_preprocess_hook
- Another preprocessor for theming engines but specific to a single hook. -
engineName_preprocess
- This is the first preprocessor that can be used inside the theme. It can be named after the theme engine the theme is running under. Applies to all hooks. -
engineName_preprocess_hook
- Another preprocessor named after the engine but specific to a single hook. -
themeName_preprocess
- This one is named after the theme itself. Applies to all hooks. -
themeName_preprocess_hook
- Same as the previous preprocessor but for a specific hook.
There are many possibilities here for modifying the variables. In most cases, it is only the first two preprocessors that exists. The first, adding the default baseline variables and the second, adding a set specific to the theming hook. Contributed modules taking advantage of the preprocessor slots (3 & 4) should document their behavior. It will not be covered extensively here.
While it is possible, the default PHPTemplate does not inject itself to this list. (5 & 6)
Themes can start adding their preprocessors seventh in the list. Although impractical, it is possible to grow this list beyond the ten shown above through sub-theming by adding strictly through the theme name as it is shown in the last two examples.
A few notes:
- It is recommended that base themes use the engine name (7 & 8) for its preprocessor. This makes it easier to move around code between themes and post snippets on Drupal.org.
- The theme name (9 & 10) should always be used for sub-themes. This minimizes any chance of fatal errors due to duplicate functions which are illegal in PHP.
- In order for your theme to have its preprocessors recognized, the template associated with the hook must exist inside the theme. When a default template exists, copy it to your theme and clear the registry. If you are converting a theme function into a template, read the parent page on getting the hook to register as a template.
Note that nothing should be returned from these functions and the variables have to be passed by reference indicated by the ampersand before variables, e.g., &$variables.
Since the variables set early on are run through all the latter preprocessors due to references, be careful that you do not inadvertently reset any added before your theme. It is fine to reset them but doing so accidentally can keep you guessing on what went wrong.
Example set from a module implementing the hook of "foo":
<?php
function template_preprocess_foo(&$variables) {
$variables['foo_list'] = array(
'list item 1',
'list item 2',
'list item 3',
);
}
?> And the preprocessor created from the theme to add to the variable set above:
<?php
function drop_preprocess_foo(&$variables) {
// Do not do this unless you mean to:
$variables['foo_list'] = array('list item 4');
// Instead do this:
$variables['foo_list'][] = 'list item 4';
}
?> The variables that end up in the template file are the keys set within $variables. So, with the above example, the variable in the template would result in $foo_list.
Example from a module
1
I don't know if it's good to use an example from a module here, that should probably better go into the module developer's theming guide. Maybe it's better to give the array $variables for the themer to work with in the second preprocessor function instead of showing the preprocessor function defined in a module.
2
I would also add the numbers of the preprocessors (1 through 10) to the examples, respectively: 2 and 10.
3
And I think it's a good idea to emphasize which kind of preprocessor functions are the most commonly used by themers (7&8, 9&10 for subthemes), and not put that information in the notes.
4
I think a more realistic example of a preprocessor function is needed.
-Niels