CHAPTER 9 ■ THE THEME SYSTEM
The field.tpl.php File
This template file is used for theming fields and, unlike the previous templates, isn’t automatically called by Drupal when rendering fields. If you wish to use this template, you’ll need to copy it from
/modules/fields/templates into your theme’s directory.
<div class="<?php print $classes; ?> clearfix"<?php print $attributes; ?>> <?php if (!$label_hidden) : ?>
<div class="field-label"<?php print $title_attributes; ?>> <?php print $label ?>: </div>
<?php endif; ?>
<div class="field-items"<?php print $content_attributes; ?>> <?php foreach ($items as $delta => $item) : ?>
<div class="field-item <?php print $delta % 2 ? 'odd' : 'even'; ?>" <?php print $item_attributes[$delta]; ?>>
<?php print render($item); ?></div> <?php endforeach; ?>
</div>
</div>
The variables that are available by default to the field.tpl.php file are shown in Table 9-6.
Table 9-6. Standard Variables Available to field.tpl.php
Variable |
Description of contents |
|
|
$items |
An array of field values; use render() to output them. |
$label |
The item’s label |
$label_hidden |
A flag (TRUE or FALSE) that can be used to set whether the label |
|
should be displayed |
$classes |
A string of classes that can be used to style contextually through CSS; it |
|
can be manipulated through CSS. It can be manipulated through the |
|
variable $classes array from preprocess functions. The default values |
|
can be one or more of the following: |
|
field: The current template type, i.e., “theming hook” |
|
field-name-[field_name]: The current fieldname; for example, if the |
|
fieldname is “field_description”, it would result in “field-name- |
|
field-description”. |
|
field-type-[field_type]: The current field type; for example, if the |
|
field type is “text”, it would result in “field-type-text”. |
|
field-label-[label_display]: The current label position; for example, |
|
if the label position is “above”, it would result in “field-label-above”. |
211
CHAPTER 9 ■ THE THEME SYSTEM
Continued
Variable |
Description of contents |
|
||
|
|
|||
$element['#object'] |
The entity that the field is attached to |
|||
$element['#view_mode'] |
The view mode of the entity that the field is attached to, e.g., “full” or |
|||
|
“teaser” |
|
|
|
$element['#field_name'] |
The |
|
fieldname |
|
$element['#field_type'] |
The field type |
|
|
|
$element['#field_language'] |
The field language |
|
|
|
$element['#field_translatable'] |
Whether the field is translatable |
|||
$element['#label_display'] |
Po |
sition |
of |
label display: inline, above, or hidden |
$field_name_css |
The CSS-compatible fieldname |
|||
$field_type_css |
The CSS-compatible field type |
|
||
$classes_array |
Array of HTML class attribute values; it is flattened into a string within |
|||
|
the variable $classes. |
|
||
|
|
|
|
|
The block.tpl.php File
The block-level theming template, block.tpl.php, can be found in the modules/block directory. By this point, you should be seeing a definitive pattern of how template files are constructed.
<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>
<?php print render($title_prefix); ?> <?php if ($block->subject): ?>
<h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2> <?php endif;?>
<?php print render($title_suffix); ?>
<div class="content"<?php print $content_attributes; ?>> <?php print $content ?>
</div>
</div>
The variables that are available by default to the block.tpl.php file are shown in Table 9-7.
212
CHAPTER 9 ■ THE THEME SYSTEM
Table 9-7. Standard Variables Available to block.tpl.php
Variable |
Description of contents |
|
|
$block->subject $content $block->module $block->delta $block->region $classes
$title_prefix (array)
$title_suffix (array)
#classes_array (array)
$block_zebra $block_id $id
$is_front
$logged_in $is_admin
$block_html_id
The |
block |
title |
The block’s content
The module that generated the block
An ID for the block, unique within each module
The block region embedding the current block
A string of classes that can be used to style contextually through CSS; it can be manipulated through the variable $classes array from preprocess functions. The default values can be one or more of the following:
block: The current template type, i.e., “theming hook”
block-[module]: The module generating the block; for example, the user module is responsible for handling the default user navigation block. In that case, the class would be “block-user”.
An array containing additional output populated by modules, intended to be displayed in front of the main title tag that appears in the template
An array containing additional output populated by modules, intended to be displayed after the main title tag that appears in the template
An array of HTML class attribute values; it is flattened into a string within the variable $classes.
Outputs “odd” and “even” dependent on each block region
Dependent on each block region
Same output as $block_id but independent of any block region
A flag (TRUE or FALSE) that indicates whether the current page is the home page of the site
A flag (TRUE or FALSE) that indicates whether the visitor is logged in
A flag (TRUE or FALSE) that indicates whether the visitor is logged in as an admin user
A valid HTML ID that is guaranteed unique
213
CHAPTER 9 ■ THE THEME SYSTEM
Overriding Template Files
There will likely come a time where you need to change how page.tpl.php, node.tpl.php, or any of the other standard template files display elements on your site. Let’s step back to our Grayscale theme that we created at the beginning of the chapter and customize the page.tpl.php file so that when a visitor is on the front page of the site, a welcome message is displayed. If the visitor isn’t on the front page, we won’t display the welcome message. To begin the process, copy the page.tpl.php file from the modules/system directory into the sites/all/themes/grayscale/templates directory. By copying the file into our theme’s directory, Drupal will now use that version of page.tpl.php rather than the one in the modules/system directory.
The modification that we’ll make is relatively simple. We’ll use the $is_front variable that is exposed to the page template, and using a conditional phrase, check to see if the visitor is on the front page. If so, we will display a “Welcome to My Site” message at the top of the page. Open the file and look for the following line:
<div id="content" class="column"><div class="section">
Immediately after that line, insert the following line of code, which uses the $is_front variable to see if the visitor is on the front page of your site, and if so, prints out a welcome message.
<?php
if ($is_front): ?><div id="welcome_message"> <?php print "Welcome to My Site!"; ?></div>
<?php endif; ?>
The result is that “Welcome to My Site!” is printed right under the secondary menu. It is nothing spectacular, but it demonstrates the concept of leveraging the standard page.tpl.php file and customizing.
■ Note If your custom page.tpl.php file doesn’t appear to be working, remember to visit admin/config/development/performance and clear your site’s cache.
You can also create custom .tpl files for specific pages of your site; for example, you could copy page.tpl.php and create a page--front.tpl.php file. This new template would be applied only to the front page of your site. You can also do the same thing with node.tpl.php. Let’s say you want to theme articles differently than other node types, like a basic page. You can copy node.tpl.php from the modules/node directory to your theme directory and rename that file to node--article.tpl.php. This new template file will override the standard node.tpl.php file for any node that is an article. For additional details, visit the theming guide on Drupal.org at http://drupal.org/documentation/theme.
■ Note There are two dashes between node and article. Drupal requires two dashes.
214