Drupal 7 Module Development

Drupal’s Theme Layer
'menu_tree__' . $menu_name,
'menu_tree',
);
theme($hook, $tree);
This allows themers to provide either a THEME_menu_tree__menu_block__1()
function to override the display of just the 1st configured menu block (with a
delta ID of 1), or to override the display of all trees displaying the management
menu with a THEME_menu_tree__menu_block__management(). Of course, if the
theme provides none of those functions, theme() will continue to use the default
implementation, theme_menu_tree(). To be clear about how this works, theme()
takes the array of suggestions and checks them from left to right until it finds an
actual implementation.
If you look at the preceding figure again, you'll notice that after the preprocess and
process functions have been run, theme() examines the $variables for additional
theme hook suggestions. Of course, only the calling code can specify hook suggestions
in the first parameter to theme(). In order to allow other modules and themes to add
its own suggestions, theme() will examine two variables $theme_hook_suggestion
and $theme_hook_suggestions. theme() will first check the singular form of that
variable name. If the $theme_hook_suggestion string doesn't match an actual
implementation, theme() will check the $theme_hook_suggestions array from
left to right to find an implementation. If theme() doesn't find any implementations
from those two variables, it will continue to use the theme hook it had previously
been using.
Since themes can completely override the value of $theme_hook_suggestion, it
is recommended that modules stick to modifying the $theme_hook_suggestions
array. This is how it is done:
// Add our suggestions to the front of the list, since our
// module is the most important one in the universe!
array_unshift($variables['theme_hook_suggestions'],
'links__retro__geocities', 'links__retro');
Note that $theme_hook_suggestions and $theme_hook_suggestion do not
take patterns. If you want theme() to look for links__retro__geocities
and links__retro, you'll need to provide both of those strings in the
$theme_hook_suggestions array.
One last note, all of the above examples assumed theme functions, but the same is
true for theme hook suggestions of template files. If you provide a node__blog__1
pattern to theme(), it will search for a node--blog--1.tpl.php file and then for a
node--blog.tpl.php file.
[ 84 ]