Drupal 7 Module Development

Drupal’s Theme Layer
The theme() function would discover that the typical_hook theme hook was
implemented as a template and render the corresponding typical-hook.tpl.php file.
As we mentioned earlier in the chapter, the only valid
characters in theme hook names are alphanumeric characters
and underscores. This is true of all theme hooks, regardless
of whether they are implemented as a theme function or as
a template file. However, when theme() looks for template
implementations, it will automatically convert any underscores
in the theme hook name into hyphens while searching for the
template file. For example, calling theme('user_picture',
$variables) will result in the template file named userpicture.tpl.php
being rendered.
Also, just like theme functions, other modules can modify the variables using
preprocess functions.
In template files the focus is on printing out variables in various places in the
markup. So for template files, the preprocess function takes on a more important
role. The only difference between a theme function's preprocess functions and a
template file's are the number and type of preprocess functions.
The preprocess zoo
When you write a theme function, its natural to pass the raw data in as parameters
and generate any display-related meta-data inside the function. With a template
file, that's not really possible without putting complex PHP inside the template.
However, as was stated earlier, all of the PHP in a template file should be limited to
just the bare minimum required to print out a PHP variable. Any processing that we
need to do on the raw data parameters to ease it into print-ready variables should be
done in preprocess functions.
"template_" preprocess functions
When a module defines a theme hook by creating a template file, that module should
also create a corresponding preprocess function to set up and process any variables
that are needed by the template file, but are not passed as parameters to theme().
By convention, that preprocess function should be of the following form:
template_preprocess_[theme hook name](&$variables)
The template_ prefix tells Drupal's theme system that this preprocess function is
the primary preprocessor for the theme hook's variables and should be run before
any other module's preprocess function.
[ 72 ]