The Definitive Guide to Drupal 7

Suggestions and Theme Functions

As explained in the “Suggestions and Template Files” section, alternate $theme_hook_suggestions are usually defined in the preprocess function for that hook. This works well because template files usually serve a specific purpose, like printing a specific entity such as a node or block. Theme functions, however, are much more diverse and end up being used within many different types of output, such as form elements, fields, and render elements. Module developers may also use theme functions to create one-off, custom content. This makes the prospect of implementing a theme function override of a widely used function such as theme_links() much less attractive, as it could potentially break styling in unexpected places all over your site.

Luckily, theme hook suggestions also exist for many theme functions, and Drupal core has implemented suggestions for some of the popular theme functions, like theme_links(). Using theme hook suggestions with theme functions simply means that you can choose to override a theme function in a specific context as opposed to overriding the base theme function, which would have a site-wide effect.

As mentioned, theme_links() is a good example of where to use theme hook suggestions when overriding theme functions. This theme function is used in many, many places, such as the main navigation, node, comment, and contextual links. Note that to implement the functions named in the “Theme function equivalent” column in Table 15–5, you need to replace THEME with the name of your theme in template.php.

Table 15–5. Some Example Template Suggestions for theme_links()
Suggestion Theme Function Equivalent Description
links THEME_links() Default implementation, which is used for all implementations unless a more specific implementation like those below is specified.
links__node THEME_links__node() Targeted implementation of theme_links() that only applies to links lists inside of nodes.
links__comment THEME_links__comment() Targeted implementation of theme_links() that only applies to links lists inside of comments.
links__contextual THEME_links__contextual() Targeted implementation of theme_links() that only applies to links generated for contextual links.
links__contextual__node THEME_links__contextual__node() Targeted implementation of theme_links() that only applies to contextual links inside of nodes.

You’ll notice in Drupal’s default page.tpl.php file, located in the main and secondary menus are printed using suggestions. You might also notice that theme functions called theme_links__system_main_menu() and theme_links__system_secondary_menu() do not exist, and that’s okay. In this case, the base hook, or the fallback, theme_links() will be used unless a more targeted theme function is created (see Listing 15–16).

Listing 15–16. Excerpt from modules/system/page.tpl.php
  1. <?php if ($main_menu || $secondary_menu): ?>
  2. <div id="navigation"><div class="section">
  3. <?php print theme('links__system_main_menu', array('links' => $main_menu, 'attributes' => array('id' => 'main-menu', 'class' => array('links', 'inline', 'clearfix')), 'heading' => t('Main menu'))); ?>
  4. <?php print theme('links__system_secondary_menu', array('links' => $secondary_menu, 'attributes' => array('id' => 'secondary-menu', 'class' => array('links', 'inline', 'clearfix')), 'heading' => t('Secondary menu'))); ?>
  5. </div></div> <!-- /.section, /#navigation -->
  6. <?php endif; ?>

In this situation, the theme hook suggestions are hardcoded into the function arguments. When theme() processes this, it will check to see if an implementation of theme_links__system_main_menu() exists first. If the function is found, it will be used to render the content. If not, the original (or fallback) theme_links() will be used instead. theme() handles this automatically and can determine the base hook from the use of the double underscore that appears directly after it.

You are reading content from two chapters on Theme Development from The Definitive Guide to Drupal 7, written by Jacine Luisi and published by Apress on July 19, 2011. All rights reserved.