How to Name Your Overrides

At run time, Drupal is designed to seek out overrides to themeable functions before applying the default functions. The system does this by looking for files in the following order (assuming your site employs the PHPTemplate engine):

1. themename_functionname (e.g., garland_breadcrumb)

2. themeengine_functionname (e.g., phptemplate_breadcrumb)

3. theme_functionname (e.g., theme_breadcrumb)

The naming convention is the key and must be followed scrupulously, because the name establishes the order of precedence. If the system does not find a function employing either the specific theme or theme engine namespace, the system will apply the default function.

Note that if your site is not using a theme engine, you must use the theme namespace for your override (e.g., themename_functionname). If your site uses a theme engine, common practice is to name the function themeengine_functionname, but this is not required; either naming convention (themename_functionname or themeengine_functionname) will work fine.

The advantage of following the themeengine_functionname format is portability. By giving the overrides generic names, you can copy them into other themes or even duplicate an entire theme directory as the first step to writing a new theme, all without having to worry about renaming all the overrides.

Overrides in Action: How Garland Works

Let's take as a case study the Garland theme included in the default distro. The author of Garland employs a number of overrides and the way they are implemented provides us with some easily accessible examples of overrides in action. A look inside the themes directory shows the structure employed by Garland and gives us hints to this theme's approach to overrides.

Phptemplate System Override
The Garland theme employs a mix of approaches to overriding functions.

Garland employs the PHPTemplate engine that is invoked in the file paqe. tpl. php. Additionally, Garland has provided alternative versions of the following PHPTemplate engine templates:

Thp aufoor has also created a new file, template. php. The presence of the alternative files and the new template. php file indicates that the author has specified variations from the default Drupal presentation. This combination of techniques, providing duplicate templates to supersede the default PHPTemplate engine templates and overriding individual themeable functions, is an example of the two most common approaches to modifying a PHPTemplate theme.

Intercepting PHPTemplate Files

Garland includes alternative versions of several default PHPTemplate template files (.tpl. php). The contents of each of those files vary from their counterparts of the same name located in the engines/phptemplate directory.

By way of example, let's look at the two versions of the file block .tpl. php.

In the original file (located at engines/phptemplate/block. tpl. php) you will find the following:

<div id="block-<?php print $block->module .'-'. $block->delta; ?>" class="block block-<?php print $block->module ?>">

<h2><?php print $block->subject ?></h2> <?php endif;?>

<div class="content"><?php print $block->content ?></div> </div>

The version of block .tpl. php included in Garland looks like this:

<div id="block-<?php print $block->module .'-'. $block->delta; ?>" class="clear-block block block-<?php print $block->module ?>"> <?php if ($block->subject): ?>

<h2><?php print $block->subject ?></h2> <?php endif;?>

<div class="content"><?php print $block->content ?></div> </div>

The only difference between the two versions of the file is the class definition in the highlighted line. The Garland theme author has simply substituted a new CSS class to be applied to the blocks. When the Garland theme is active, the Drupal system will apply the Garland block .tpl. php, with its new class, and ignore the default file of the same name in the PHPTemplate directory. The modified file in the Garland theme takes precedence over the file of the same name in the PHPTemplate engine's directory.

The author applies a similar approach with the files comment. tpl. php and node .tpl. php, providing in these files alternative formatting to that included in the default PHPTemplate files. Compare and contrast those files to view the differences.

Overriding Themeable Functions in Garland

In addition to overriding some of the default PHPTemplate engine template files, the Garland author has also chosen to override a number of Drupal's default themeable functions.

To put these overrides into action, the author has created the file template. php. This is an optional file, and is commonly used as a convenient technique for grouping together overrides for a number of themeable functions. Whenever the PHPTemplate engine detects the presence of a template . php file inside a theme directory, it will read this file first and apply the functions contained therein.

If you open the template. php file and examine the contents, you will find overrides for the following functions:

Original function name Location of original Garland override's name











theme menu local tasks



menu local


Let's look in more detail at how a themeable function override is implemented in the Garland theme.

The default definition for the Drupal breadcrumb trail is given in the file includes/

theme. inc. The default function looks like this:

function theme_breadcrumb($breadcrumb) { if (!empty($breadcrumb)) {

return '<div class="breadcrumb">'. implode(' >> ', $breadcrumb)

The Garland theme overrides the default breadcrumb function to provide different styling. The override is contained in the file garland/template. php. The override looks like this:

function phptemplate_breadcrumb($breadcrumb) { if (!empty($breadcrumb)) {

return '<div class="breadcrumb">'. implode(' > ', $breadcrumb)

The differences are subtle, but critical. First, the function has been renamed to phptempiate_breadcrumb (the developer has adopted the themeengine_ functionname naming convention in this). The new name alerts Drupal to apply this version of the function, instead of the default theme breadcrumb function. Second, the default function decorates the elements in the breadcrumb trail with a double right arrow (">>"), while the override changes the decorative element to a single right arrow (">"). The result is that the Drupal system recognizes the function placed in the theme file first, and applies a single right arrow to separate the items in the site's breadcrumb trail.

To see this in action, try substituting "*" for ">" in the phptempiate_breadcrumb code. Save your modified file and reload the page in your browser. You should see the breadcrumb decoration change from a single right arrow to an asterisk.

+1 0

Post a comment