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
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.
|Suggestion||Template File Equivalent||Description|
||Default block implementation.|
Because of their special nature as the highest-level template files in Drupal, both
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
html.tpl.php templates for just about any page on your site.
Some observations of
- 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.phpwhen 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