This chapter is from the book
This chapter is from the book
This chapter is from the book
Sitewide Page Variables
The variables available in the template file page.tpl.php are classified into several categories:
- General utility variables are used to build context-sensitive templates with directory names relevant to the path of the theme’s location on the server.
- Page metadata includes page language, style and script tags relevant to the page, and body classes.
- Site identity takes the form of the site name, site slogan, site mission, and logo.
- Navigation includes items related to primary and secondary navigation, as well as search boxes.
- Page content includes the page title, dynamic help text and Drupal system messages, and tabs.
- Footer and closing data includes RSS feed icons, footer messages, and final markup from any modules (“closure”).
Commonly used variables are identified in Figure 4.2, which depicts a fresh installation of Drupal, using the theme Garland.
)
Figure 4.2 Common variables displayed in the Garland theme.
A complete list of page template variables is available from the Drupal directory modules/system, in the file page.tpl.php, which is also available online at http://api.drupal.org/api/file/modules/system/page.tpl.php.
General Utility Variables
The general utility variables represent a very basic toolkit with which you can customize your site’s template based on the characteristics of the visitor. They include the following variables:
- Variables useful in linking to images and files within your site, such as $base_path (the base URL for the Drupal installation) and $directory (the base directory for this theme)
- $is_front, which reports if the current page is the front page of the site
- User status checks, including the test of whether the visitor is logged into the site ($logged_in) and whether the user has access to administration pages ($is_admin)
Page Metadata
The page metadata variables are used in the <head> tag of the page template. This set includes the following variables:
- An object containing the language the site is being displayed in. To print the text representation of the language to your template, use the following variable: $language->language.
- $head_title: A modified version of the page title containing the site name, for use in the <title> tag.
- $head: Metadata for metatags, keyword tags to be inserted into the <head> section.
- $styles: Style tags used to link all CSS files for the page.
- $scripts: Script tags used to load the JavaScript files and settings for the page.
In addition to this metadata, there is a wonderful variable that contains a set of conditions to help you style each page: $body_classes. The $body_classes variable includes the following information: the current layout (multiple columns, single column); whether the current visitor is an authenticated user; and the type of the node being displayed (for example, node-type-book). This variable includes only the names of the classes to be used by your style sheets. To use it in your theme, you must include the following PHP snippet:
<body class="<?php print $body_classes ?>">
Site Identity
The site identity information comprises a set of variables that outputs information about your site. You can alter the contents of and/or disable each of these variables in Drupal’s administration area by navigating to Administer, Site configuration, Site information.
- $front_page: The URL of the front page. Use this variable instead of $base_path when linking to the front page. It includes the language domain or prefix.
- $logo: The path to the logo image, as defined in the theme.
- $site_name: The name of your Web site.
Two other variables can be set within the site identity section of the Drupal administration area:
- $site_slogan: The slogan of the site.
- $mission: The text of the site mission.
There is no rule that says you must use these last two variables for their intended purpose; in fact, you can use them to store any information you would like to display within your page template.
Page Content, Drupal Messages, and Help Text
Content is the most important part of your Web site. You must tell Drupal where to insert content into the page template! This is done with a simple variable, $content. You may place this variable anywhere in the template file page.tpl.php. From this simple variable, Drupal may present a single node, or a list of nodes, or whatever else Drupal may prepare as the “content” for any given page.
You must also print the title for this content using the variable $title. It is different than the variable $head_title, which includes the name of the Web site and is typically printed in the <title> tag for a page.
There are two modes for each node: view and edit. These modes can be accessed through the tabs that are displayed on each node. Within your page template, the variables $tabs (primary level of tabs) and $tabs2 (subnavigation available present in several administrative pages) are used to place links that access the “view” and “edit” modes for each node. The tab variables are typically printed between the $title and $content variables.
Breadcrumbs
Although there is a variable containing the breadcrumb path for each page, the breadcrumb trail is often incomplete. Many themes choose to display this variable only in the administrative section of the Web page.
Drupal communicates system messages to the user through the variable $messages. This variable may contain useful information that describes the successful submission of new content or content modifications, errors relating to a form submission, or messages within the administration system. Messages come in three flavors: status, warning, and error. Through your style sheet you can make these messages visually unique. Typical colors used for these messages are green for status messages, yellow for warning messages, and red for error messages. The messages are available as CSS classes and carry the corresponding name (for example, warning messages use the CSS selector .warning).
In addition to these system messages, Drupal will occasionally provide “help” text, which is made available through the variable $help. Both the help text and messages must be specified in your page template to ensure that the appropriate system messages are delivered to your Web site users.
Creating New Page Variables
In addition to using the variables that are provided by Drupal, you can create your own. Each time Drupal builds a page, it gathers the information it needs to display that page and makes sure the information is safe to display. This “preprocessing” is completed before the page is built using the template files. To keep your template files focused only on HTML output, you can insert any custom programming you need into the relevant preprocess function. Its output will be returned as a variable to the relevant tpl.php template file. Variables created in the preprocess functions are available only in the relevant template files (tpl.php).
Placing PHP snippets into templates
Throughout the rest of this chapter, you will be working with preprocess functions and creating new theme variables. The preprocess functions are always placed in your theme’s template.php file. Theme variables are always placed in the relevant template file (for example, page.tpl.php).
Preprocess functions are named according to the template you want to “hook” your new variables to. Any module that has a template file can use the preprocess function. For example, the page, node, comment, and block types all have associated .tpl.php files; as a consequence, they can all be tied to a preprocess function. A full list of preprocess functions is available from the API documentation at http://api.drupal.org/api/search/6/preprocess. More information on creating additional template files is provided later in this chapter.
In the following example, you will add a new variable that can be used in the template page.tpl.php. Your imagination is the only limit on what these variables can contain! The Zen theme inserts additional, sophisticated body classes that allow you to create very specialized page customizations through CSS. The Garland theme uses a preprocess page function to hook into the color module. Later in this chapter, you will learn how to add new image banners based on which section of the Web site you are viewing.
In this example, we will add a new graphic to the page if the visitor is logged into the site but is not currently viewing the front page.
function bolg_preprocess_page (&$variables) {
// Add a "go home" button to page.tpl.php
if ($variables['logged_in'] == TRUE && $variables['is_front'] == FALSE) {
$image_path = $variables['directory'] . "/images/go_home.jpg";
$image_text = t("Go home!");
$image = theme('image', $image_path, $image_text, $image_text);
$variables['go_home'] = l($image, "<front>", array('html'=> TRUE));
}
} // End of the preprocess_page function
In the file page.tpl.php, you can now place the new variable $go_home anywhere you would like the button to appear. Although the snippet could be simplified by hard-coding the HTML for the image, this method can be easily reused in many different themes and allows the text string to be translated for multilingual Web sites.
Modifying Page Variables
You may also choose to modify variables that have already been set by Drupal. The Zen theme uses this technique to remove the markup for an empty help message. The Newswire theme customizes page variables to modify the HTML for the content title depending on which page is being viewed; Newswire also customizes the logo that is displayed on the front page and the inner pages of the site. The Acquia Marina theme removes the markup for sidebars when they are not in use to create a clean, collapsible template layout. You can implement your own customizations as well.
To reset a variable, simply use the same variable name as an existing page variable. Do not unset unused variables, as this action may cause an ugly PHP error if the page.tpl.php file tries to print a variable that no longer exists. Instead, set the unused variable to a blank string:
function bolg_preprocess_page (&$variables) {
// From the Zen theme
// Don't display empty help from node_help().
if ($variables['help'] == "<div class=\"help\"><p></p>\n</div>") {
$variables['help'] = '';
}
}
In addition to the techniques you will encounter later in this chapter, much can be gleaned from other themes. Download and examine a variety of themes to see how other people have customized their page templates by adding, and modifying, their template variables.