template.php

The template.php file contains your sub-theme's functions to manipulate Drupal's default markup. It is one of the most useful files when creating or modifying Drupal themes. With this file you can do three things:

• Modify any theme hooks variables or add your own variables, using preprocess or process functions.
• Override any theme function. That is, replace a module's default theme function with one you write.
• Call hook_*_alter() functions which allow you to alter various parts of Drupal's internals, including the render elements in forms. The most useful of which include hook_form_alter(), hook_form_FORM_ID_alter(), and hook_page_alter(). See api.drupal.org for more information about _alter functions.

Overriding theme functions

If a theme hook uses a theme function, Drupal will use the default theme function unless your theme overrides it. To override a theme function, you have to first find the theme function that generates the output. (The api.drupal.org website is a good place to find which file contains which function.) Then you can copy the original function in its entirety and paste it in this template.php file, changing the prefix from theme_ to foo_. For example:

original, found in modules/field/field.module: theme_field()
theme override, found in template.php: foo_field()

where foo is the name of your sub-theme. For example, the zen_classic theme would define a zen_classic_field() function.

Note that base themes can also override theme functions. And those overrides will be used by sub-themes unless the sub-theme chooses to override again.

Zen core only overrides a handful of theme functions. If you wish to override one of them, you should first look at how Zen core implements this function:

• theme_breadcrumbs() in zen/template.php
• theme_menu_local_tasks() in zen/template.php
• theme_menu_local_task() in zen/template.php
• theme_status_messages() in zen/template.php
• theme_mark() in zen/template.php

For more information, please visit the Theme Developer's Guide on Drupal.org: http://drupal.org/node/173880

Create or modify variables for your theme

Each tpl.php template file has several variables which hold various pieces of content. You can modify those variables (or add new ones) before they are used in the template files by using preprocess functions.

This makes THEME_preprocess_HOOK() functions the most powerful functions available to themers.

It works by having one preprocess function for each template file or its derivatives (called theme hook suggestions). For example:

For more information on preprocess functions and theme hook suggestions, please visit the Theme Developer's Guide on Drupal.org: http://drupal.org/node/223440 and http://drupal.org/node/1089656