Drupal 7 Module Development

Chapter 3
We've actually already discussed most of the work flow of theme(). There's only one
aspect we haven't yet seen. So far, we've only called theme() with a simple string
passed to its $hook parameter. However, we can actually pass more complex data to
it and make use of the theme system's theme hook suggestions.
Theme hook suggestions
So re-using theme hooks in various places in our code is a good thing, of course.
However, one problem you'll encounter is that theme functions lose context when
a theme hook is re-used. For example, theme_links() has no idea if it's theming
node links or comment links, which makes it difficult to style them differently.
Fortunately, we can provide context to the theme system by providing a theme hook
pattern as its first parameter:
[base hook]__[context]
The parts of the pattern are separated with a double underscore since some theme
hooks (like user and user_profile) could be confusing if we were to use a single
underscore to delineate the parts of the pattern. In fact, we can provide additional
contexts if needed, as follows:
[base hook]__[context]__[even more context]__[don't get crazy]
So how does this work and how does it help? In Drupal 7, we theme the
node's links by calling theme('links__node', $vars). So theme() will use a
theme_links__node() function if one has been provided. However, if one doesn't
exist, it will use theme_links(). This allows us to know the context based on the
theme function we are implementing. A more complex example is when Drupal 7
themes the node's contextual links; it calls theme('links__contextual__node',
$vars). So, theme() will search for a theme_links__contextual__node(), then
for theme_links__contextual(), and lastly theme_links(), shortening the
pattern by one unit of context each time.
The theme hook pattern is an easy-to-use method of providing context, but some
contributed modules need to provide more complex lists of context than the simple
string pattern can provide. For this reason, an array of possible hook suggestions can
also be passed to theme(). For example, both Views and the Menu block module
use this method. While theming trees of menus, Menu block provides the following
array to theme:
$hook = array(
'menu_tree__menu_block__' . $delta,
'menu_tree__menu_block__' . $menu_name,
'menu_tree__menu_block',
[ 83 ]