Last updated February 13, 2015. Created on October 21, 2004.
Edited by dokumori, SLIU, marcvangend, mikhailian. Log in to edit this page.

If you want to override a theme function not included in the basic list (block, box, comment, node, page), you need to tell PHPTemplate about it.

To do this, you need to create a template.php file in your theme's directory. This file must start with a PHP opening tag <?php but the close tag is not needed and it is recommended that you omit it. Also included in the file are stubs for the theme overrides. These stubs instruct the engine what template file to use and which variables to pass to it.

First, you need to locate the appropriate theme function to override. You can find a list of these in the API documentation. We will use theme_item_list() as an example.

The function definition for theme_item_list() looks like this:

<?php function theme_item_list($items = array(), $title = NULL) {
 
$output = '<div class="item-list">';
  if (isset(
$title)) {
   
$output .= '<h3>'. $title .'</h3>';
  }
?>

Now you need to place a stub in your theme's template.php, like this:

<?php
/**
 * Catch the theme_item_list function, and redirect through the template api
 */
function phptemplate_item_list($items = array(), $title = NULL) {
 
// Pass to phptemplate, including translating the parameters to an associative array.
  // The element names are the names that the variables
  // will be assigned within your template.
 
return _phptemplate_callback('item_list', array('items' => $items, 'title' => $title));
}
?>

We replaced the word theme in the function name with phptemplate and used a call to _phptemplate_callback() to pass the parameters ($items and $title) to PHPTemplate.

Now, you can create a file item_list.tpl.php file in your theme's directory, which will be used to theme item lists. Start by putting in the code from the original theme_item_list(). Do not wrap this code into a function, write inline, e.g.

<?php
  $output
= '<div class="item-list">';
  if (isset(
$title)) {
   
$output .= '<h3>'. $title .'</h3>';
  }
?>

Note that you will need to visit [ Administer -> Site building -> Themes ] for PHPTemplate to refresh its cache and recognize the new file. Beginning with version 4.6, this is not necessary anymore.

In addition to Drupal's standard theme functions (as shown in the API) you can also override any Drupal form using a theme function. For example, given a Core form that is created from a form builder function, the form_id can be used to override. A worked example makes this clearer.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

lsiden’s picture

I would like to see this page also explain the trade-offs in deciding whether to name the function over-ride 'phptemplate_' or 'mytemplate_'. I know I saw this mentioned somewhere, either on this site, or in the Pro Drupal Development book, but can no longer find it, even after extensive searching. Or I can do it myself if someone can point me to where this was originally mentioned. In that case, I'll just insert a hypertext link to the relevant page and section. Thanks in advance.

DrupalNovice’s picture

This won't work in Drupal 6 as _phptemplate_callback() stopped being supported in that version

brst t’s picture

Here's how to implement a hook_menu_alter in template.php in 6.x to say, rename a default aggregator menu item. Here, the path /aggregator from the default 'Feed aggregator' to 'Latest news'

//rename default title 'Feed aggregator' to 'Latest news'
function aggregator_menu_alter (&$callbacks) {
  $callbacks['aggregator']['title'] = 'Latest news';
}
craigkendall’s picture

in what file and where does this need to go... It's kind of unclear.

brst t’s picture

No change in the location of the file in which to put this -- template.php in your theme is where these pre-process type of functions typically go.

Here's a good backgrounder with some examples: http://drupal.org/node/223440
And with more text and fewer examples check out: http://drupal.org/node/341628 (plus the next two in the 'book' http://drupal.org/node/457740 and http://drupal.org/node/173880)

spacetaxi’s picture

Since _phptemplate_callback() is apparently dropped from Drupal 6, I just left it out.

Instead, copy the original theme function to your tempate.php file, rename the function "phptemplate_*" instead of "theme_*", and make your code changes.

You then need to refresh the theme registry to see your changes. See: http://drupal.org/node/173880#theme-registry

inventlogic’s picture

This was a basic piece of common sense that eluded me for several hours. I wanted to edit the theme layout of the Color Module as shown on my template's settings page and immediately I placed the theme override function for the module in my default template's template.php. It didn't occur to me that I was using a different theme for Admin. Eventually realized the Admin theme has its own template.php which is where you have to place overrides of the admin theme. Just mentioning for future reference.