The Definitive Guide to Drupal 7

Suggestions and Template Files

All of the common template files listed in Table 15–1 can be overridden to allow for more targeted customization by simply changing the name of the template file. When working with blocks, for example, Drupal suggests the options in Listing 15–15 during template_preprocess_block().

Listing 15–15. Excerpt from template_preprocess_block() where template suggestions for block template files are defined.
  1. <?php
  2. $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->region;
  3. $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->module;
  4. $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->module . '__' . $variables['block']->delta;

Drupal automatically converts the underscores to dashes and searches for these templates in your theme when determining which one to use. This code translates to the suggestions shown in Table 15–4.

Table 15–4. Template Suggestions for Blocks
Suggestion Template File Equivalent Description
block block.tpl.php Default block implementation.
block__REGION block--REGION.tpl.php REGION is replaced with the theme region name, and the template targets blocks in that region.
block__MODULE block--MODULE.tpl.php MODULE is replaced with the name of the module that created the block. For example, a template file that targets custom blocks would be block--block.tpl.php and a block created by the menu module would be targeted by using block--menu.tpl.php.
block__MODULE__DELTA block--MODULE--DELTA.tpl.php The DELTA value, which used to be a number in previous versions, is the system name of the block as defined by the module. For example, to target the System module’s Navigation block, you would use block--system--navigation.tpl.php. In this example, “system” is the module and “navigation” is the delta.

Page-Level Suggestions

Because of their special nature as the highest-level template files in Drupal, both html.tpl.php and page.tpl.php are given special attention when it comes to generating their suggestions. A function called theme_get_suggestions() is used to automatically generate suggestions using arguments based on the context of the current page. This means that if you wanted to, you could literally have a different version of these template files for every page on your site. Of course, this is something you should never even think about doing, but in certain cases, like a very different home page or landing page, having a different page.tpl.php makes perfect sense.

As mentioned, the theme hook suggestions for these files are generated with the help of arguments. Arguments in Drupal are the elements or pieces of system path of a page. For example, when viewing the URL http://yoursite.com/node/1, the first argument is “node” and the second argument is “1.” Understanding arguments in Drupal is one of the key things that will help you understand Drupal. They are extremely useful in determining context and can allow you to perform more advanced manipulations in your theme.

Figure 15–17 illustrates how you can use theme hook suggestions and arguments to make separate page.tpl.php and html.tpl.php templates for just about any page on your site.

Diagram of how theme hook suggestions work
Figure 15–17. Suggestions for page.tpl.php on different types of pages.
* Drupal’s front page is set to “node” by default under Admin » Configuration » Site Information. This page is not a typical node. It is a custom page provided by the node module’s node_page_default() function. It lists posts that have been marked as “Promote to front page.” The “front” suggestion is specific to the front page (or home page), regardless of what type of page it is. Should you change your front page to a different path, additional suggestions will become available to you.

Some observations of $theme_hook_suggestions include:

  • Underscores are used instead of dashes.
  • File extensions are not present because these hooks can be implemented as theme functions or template files. At this stage in the process, it doesn’t matter whether a template or a theme function will be used. When it’s time to render the content, theme() will determine which should be used and make the necessary adjustments.
  • Each suggestion begins with a hook__ (double-underscore) prefix. In the example shown in Listing 15–15, that hook is block. This allows Drupal to fall back on the generic theme hook, which in this case is block, and use block.tpl.php when a more specific template, like block--module.tpl.php, doesn’t exist.

The order in which these suggestions appear in the $theme_hook_suggestions variable determines which hook/template file will be used in FILO (first in, last out) order. When it comes time to render the template, the last suggestion will be used, with one exception. A variable called $theme_hook_suggestions (note that it is singular, not plural) is also available. If it’s set by a module or theme, it will take precedence over anything defined in $theme_hook_suggestions.

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.