Drupal 7 Module Development

Drupal’s Theme Layer
Preprocess functions
Now we're starting to see the real flexibility of the theme system. Preprocess
functions allow one module to alter the variables used by another module when it
calls a theme hook. So if some code passes data to theme() for a particular theme
hook, preprocess functions will be called to alter the data before the actual theme
hook implementation is called. The following steps are carried out:
1. Code calls theme('hook_name', $variables).
2. theme() calls preprocess functions for hook_name.
3. Preprocess functions modify variables.
4. theme() calls actual implementation for hook_name with modified variables.
All preprocess functions take the form of:
[module]_preprocess_[theme hook name](&$variables)
So if the foo module wants to alter the variables for the item_list theme hook, it
could define the function as follows:
function foo_preprocess_item_list(&$variables) {
// Add a class to the list wrapper.
$variables['attributes']['class'][] = 'foo-list';
}
Notice that the $variables parameter is defined with an ampersand in front of
it. That's PHP notation to pass the parameter by reference. Instead of getting a copy
of the variables, the foo_preprocess_item_list() function will get access to the
actual $variables which is later passed to the theme function implementation. So
any modifications that the preprocess function makes to the $variables parameter
will be preserved when those variables are passed to the theme function. That's
the reason our example foo_preprocess_item_list() function doesn't return
anything; its work is done directly on the original $variables.
This is extremely handy for module developers as it allows all sorts of integration
with other modules. Since the variables parameter is a mix of data and options,
modules can alter both the raw data and change the way data will be rendered. This
can be as simple as one module needing a special class for use in its JavaScript code
and adding that class to another module's themed content by appending to the $var
iables['attributes']['class'] array, or can be more complex interactions like
the i18n module translating the language used in blocks.
Imagine we've built a retro module that integrates GeoCities and we want to replace
all links to a user's profile page with a link to the user's GeoCities homepage. We can
do that relatively easily with a preprocess function.
[ 68 ]