Cwgordon7's blog

Drupal 6's updated function creates considerable more support for templates. If you've even looked at a Drupal 5 theme's files or the Drupal 6 core, you've seen them. They're the little .tpl.php files.

What is a template, anyway?

A template is a file designed to be friendly to the typical administrator. There is not supposed to be any complex PHP code there, because that would scare off many a user. They're lightweight files used to generate the equivalent of what a theme_function does. Variables can be passed into the template for use through a nice php function, template_preprocess_template_name().

Why are they useful?

Say you're a typical Drupal end user who wants to customize how their site is displayed. Are you going to want to go into a long, ugly, php file looking for how to change it? Of course not. You want to have one file that allows you to easily go in, edit what you want, and leave, without any potential for bad long-term effects.

The future!

The future is templates. Theme_functions are already outdated; template files are much more powerful. With core support in Drupal 6, hopefully we'll see much more of a move towards template files. Module writers: answer the call! Write nice, user-friendly template files!

How do I actually write a template file?

It's simple! Here's the procedure:

1. In your implementation of hook_theme, add, under the applicable item:

   'template' => 'template-name-here',

   Note that it is without the .tpl.php extension, and that it uses dashes, not underscores.

2. Create the function:

   function template_preprocess_template_name(&$variables) {

   Note that here, we use underscores not dashes. In this function, set the $variables array (passed in by reference) to contain any variables you want your template to be able to use. For example:

   $variables['title'] = $node->title;

   Would pass into the function a $title variable which contained some node's title.

3. Create the template file.
   This should be name template-name-here.tpl.php (Note the use of dashes). Everything here is assumed to be html, unless contained within tags. You may make use of all variables passed in by the template_preprocess function.

   This should be a starter template, with good defaults, but should also contain sufficient comments so as to make the user aware of the variables they can use and what various aspects of the default template do. To do comments, simply do something like:

   Note that all variables passed into the template MUST be safe; for example, user input should be run through check_plain in the preprocess function. Do not put check_plain or other safety checks inside the template file, as this would be dangerous for the average user to edit.

And now you're done! You created a highly customizable yet powerful template file. Congratulations, and thank you for empowering Drupal users to customize the "look and feel" of their sites.

For further reference, see .