The Definitive Guide to Drupal 7

Global Template Variables

Template files usually contain a few more variables than they actually print. In some cases there are many more. This is a great thing for theme developers because it opens up many possibilities for manipulating the display of markup without the need for much PHP knowledge. Table 15-2 describes some of the helpful variables available in all templates (with the exception of the attribute variables; these are covered section the “HTML Attributes” section). Identifying available variables is covered in detail in the next chapter.

Table 15-2. Variables available in all templates
Variable Description
$is_admin Helper variable that equals TRUE if the currently logged in user is an administrator, and FALSE otherwise.
$logged_in Helper variable that equals TRUE if the current user is logged in, and FALSE otherwise. The $user->uid is used to determine this information, as anonymous users always have a user ID of 0.
$is_front Helper variable that uses the drupal_is_front_page() function to determine if the current page is the front page of the site. Equals TRUE on the front page (unless the database is offline), and FALSE otherwise.
$directory The directory in which the template being used is located.
$user An object that contains account information of the currently logged in user. It may be accessed by adding the line global $user; to the template you are working in. Never print any properties of it directly because it contains raw user data and thus it is insecure. Instead, use theme_username(); for example, theme('username', array('account' => $user)).
$language An object that contains information about the language currently being used on the site, such as $language->dir, which contains the text direction, and $language->language which would contain en for English. It may be accessed by adding the line global $language; to the template you are working in.
$theme_hook_suggestions An array containing other possible theme hooks, which can be used as variants for naming template files and theme functions or to determine context. See the “Theme Hook Suggestions” section.
$title_prefix and $title_suffix Render arrays containing elements, such as contextual links, to be printed before and after the title in templates or at the top and bottom of template files where a title does not exist.

HTML Attributes

In Drupal 7, we began storing attributes in arrays. Part of the reason this was done is the RDF module. The RDF module utilizes these variables to tack on its data during the preprocess phase. Another reason was to allow theme developers more control over the classes printing out in their template files in preprocess functions.

Each of these variables, described in Table 15–3, has an array and string version. The array version, which contains the suffix _array in the variable name, is populated during various preprocess functions, such as template_preprocess() and template_preprocess_node() or template_preprocess_block(). Then, during the template_process() phase, new variables containing a flattened or string version of these arrays is created for use in templates. This process is illustrated in Figure 15–15. See the “Preprocess and Process Functions” section of this chapter for more details.

Table 15–3. Pluggable HTML Attributes
Variable Description
$attributes Contains HTML attributes provided by modules (mainly RDF), except for the class attribute, which is handled separately (see below). $attributes, available as $attributes_array in preprocess, is usually reserved for the top-level HTML wrapper element, such as <body> or outermost <div> in other template files.
$classes Contains HTML classes for templates. Usually reserved for the top-level HTML wrapper element, such as <body> or outermost <div> in other template files.
$title_attributes Contains classes for the top-level heading, such as a node or block title, of the template file, which is usually an <h2> for node teaser or block content.
$content_attributes Contains classes for the content wrapper <div>, or post body of templates. An example of how these variables are used can be found in the node.tpl.php file.
Screenshot of node.tpl.php source with notes and screenshots of array output for pluggable attributes
Figure 15–15. Excerpt from node.tpl.php, which highlights how the pluggable HTML attributes are used

All of the common core templates provide detailed documentation of the available variables. A quick look at the default block.tpl.php template file, located in the modules/block directory reveals that most of the contents of the file is actually documentation for the available variables. As shown in Listing 15–8, you can get a good idea of what you have to work with by just looking at the documentation and code.

Listing 15–8. Source Code for Default modules/block/block.tpl.php, Including Variable Documentation
  1. /**
  2. * @file
  3. * Default theme implementation to display a block.
  4. *
  5. * Available variables:
  6. * - $block->subject: Block title.
  7. * - $content: Block content.
  8. * - $block->module: Module that generated the block.
  9. * - $block->delta: An ID for the block, unique within each module.
  10. * - $block->region: The block region embedding the current block.
  11. * - $classes: String of classes that can be used to style contextually through
  12. * CSS. It can be manipulated through the variable $classes_array from
  13. * preprocess functions. The default values can be one or more of the
  14. * following:
  15. * - block: The current template type, i.e., "theming hook".
  16. * - block-[module]: The module generating the block. For example, the user
  17. * module is responsible for handling the default user navigation block. In
  18. * that case the class would be 'block-user'.
  19. * - $title_prefix (array): An array containing additional output populated by
  20. * modules, intended to be displayed in front of the main title tag that
  21. * appears in the template.
  22. * - $title_suffix (array): An array containing additional output populated by
  23. * modules, intended to be displayed after the main title tag that appears in
  24. * the template.
  25. *
  26. * Helper variables:
  27. * - $classes_array: Array of html class attribute values. It is flattened
  28. * into a string within the variable $classes.
  29. * - $block_zebra: Outputs 'odd' and 'even' dependent on each block region.
  30. * - $zebra: Same output as $block_zebra but independent of any block region.
  31. * - $block_id: Counter dependent on each block region.
  32. * - $id: Same output as $block_id but independent of any block region.
  33. * - $is_front: Flags true when presented in the front page.
  34. * - $logged_in: Flags true when the current user is a logged-in member.
  35. * - $is_admin: Flags true when the current user is an administrator.
  36. * - $block_html_id: A valid HTML ID and guaranteed unique.
  37. *
  38. * @see template_preprocess()
  39. * @see template_preprocess_block()
  40. * @see template_process()
  41. *
  42. * @ingroup themeable
  43. */
  44. ?>
  45. <div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>
  46. <?php print render($title_prefix); ?>
  47. <?php if ($block->subject): ?>
  48. <h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2>
  49. <?php endif;?>
  50. <?php print render($title_suffix); ?>
  51. <div class="content"<?php print $content_attributes; ?>>
  52. <?php print $content ?>
  53. </div>
  54. </div>

At the top of the file there is a @file block, which briefly describes the purpose of the file. Underneath, there is a long list of variables, some of which are printed in the template file and some that are not. There are also @see references to applicable preprocess and process functions, which are discussed in more detail in the next chapter.

To get an up-close idea of what this template file produces, take a look at a block produced by the Bartik theme. Bartik does not include a block.tpl.php file; it uses Drupal’s default, which is provided by the Block module. Create a custom block with the title “My Custom Block” and some dummy text as the body, and place it in the Sidebar First region of the Bartik theme.

Screenshot of block configuration form
Figure 15–16. Screenshots of our rendered custom block as viewed using the Bartik theme and the configuration page for the block

Your custom block, shown in Figure 15–16 along with the block.tpl.php template file in Listing 15–8, produces the output displayed in Listing 15–9 for anonymous users. The block title is printed by <?php print $block->subject ?> and the body is printed by <?php print $content ?>. Drupal will only populate variables and display content that the user viewing it has access to.

Listing 15–9. HTML output of a custom block titled “My Custom Block” when logged out.
  1. <div id="block-block-1" class="block block-block">
  2. <h2>My Custom Block</h2>
  3. <div class="content">
  4. <p>Enim quam iusto quam iis enim. Molestie at et diam ut legere. Feugiat tation facilisis quarta soluta quam. Facilisis lectorum modo nam modo suscipit.</p>
  5. </div>
  6. </div>

Listing 15–10 shows the HTML for the same block as it is displayed to users logged in as administrators. You’ll notice that the code is different. Administrators have access to contextual administrative links, added by the Contextual Links module. These links are printed via the <?php print render($title_prefix); ?> line. The Contextual Links module also adds a class to the wrapper <div> identifying it as a contextual-links-region. This behavior is not specific to the Block module or the block.tpl.php template file. The $title_prefix and $title_suffix variables were created to allow modules to inject content before and after titles in template files, which the Contextual links module takes advantage of.

Listing 15–10. HTML Output of a Custom Block Titled “My Custom Block” When Logged In as an Administrator, Highlighting the Output of $title_suffix.
  1. <div id="block-block-1" class="block block-block contextual-links-region">
  2. <h2>My Custom Block</h2>
  3. <div class="contextual-links-wrapper contextual-links-processed">
  4. <a class="contextual-links-trigger" href="#">Configure</a>
  5. <ul class="contextual-links">
  6. <li class="block-configure first last"><a href="/admin/structure/block/manage/block/1/configure?destination=node">Configure block</a></li>
  7. </ul>
  8. </div>
  9. <div class="content">
  10. <p>Enim quam iusto quam iis enim. Molestie at et diam ut legere. Feugiat tation facilisis quarta soluta quam. Facilisis lectorum modo nam modo suscipit.</p>
  11. </div>
  12. </div>

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.