Drupal 7 Module Development

Drupal’s Theme Layer
We've also specified a pattern for that hook. After the theme registry retrieves the
information from our retro_theme() function, it will try to auto-discover any
template files whose names begin with the pattern that we specify. So the theme
registry will search for any template beginning with wonder__ and will add an entry
for it in the theme registry. When theme() is passed theme hook suggestions, it
doesn't search the file directory, it searches the theme registry instead, so this
pattern is essential to making theme hook suggestions work.
Lastly in our wonder definition, we specified several variables with the 'variables'
key/value set, namely, twin (a string), with_monkey (a boolean), and activations
(an array), and gave them each a default value.
Instead of a list of variables, the theme_austinite() function expects a single
render element as its parameter, so we need to specify the name of the render
element. We'll be able to access the render element of theme_austinite() from
$variables['my_element']. In the preceding example, we used my_element to
make it obvious that the value specified in render element is the key that needs to
be used in $variables to access that element. However, by convention, Drupal core
usually uses element or elements for that value.
To be clear, a theme hook should either use 'render element' or 'variables' in its
dataset. Note that even if you use 'variables', one of those variables can still be a
render element.
Finally, we used a file key to specify that we're storing our theme_austinite()
function in a retro.texas.inc file. theme() will lazy load this file if it needs to
use this theme hook on a particular page.
Full documentation can be found in the DocBlock for the hook_theme() API at the
following site:
http://api.drupal.org/api/function/hook_theme/7
hook_theme_registry_alter
There are some extreme cases where a module may want to alter the registry
entry for a particular theme hook. Fortunately, there's a hook for that. The
hook_theme_registry_alter() hook can be implemented to alter the theme
registry directly after it has been built with hook_theme() and the theme system's
auto-discovery mechanisms. Let's suppose a Spook module wants to control
whether Drupal's status messages are displayed to the user. If you look at
template_preprocess_page(), you'll see that the $show_messages variable
controls whether the status messages are displayed. Unfortunately, if we tried
[ 88 ]