How do I use theme preprocessor functions for my own templates?

Question

I have several .tpl.php files for nodes, CCK fields, and Views theming. These template files have a lot of logic in them to move things around, strip links, create new links, etc. I understand that this is bad development and not "The Drupal Way".

If I understand correctly, "The Drupal Way" is to use preprocessor functions in your template.php file to manipulate variables and add new variables. A few questions about that:

• Is there a naming convention for creating a preprocessor function for a specific theme? For example, if I have a CCK field template called content-field-field_transmission_make_model.tpl, how would I name the preprocessor function?
• Can I use template preprocessor functions for node templates, CCK field templates, and Views templates? Do they have different methods of modifying template variables or adding new ones?

Solution 1

For a general overview, you should read up on manipulating variables within preprocess functions.

---

Concerning the naming convention, this is normally pretty simple, but there is a catch for your current example (see below):

A preprocess functions signature needs to be

[yourModuleName|yourThemeName]_preprocess_[themeFunctionName](&$variables)

so implementing one for the page template within a themes template.php file would result in

themeName_preprocess_page(&$variables)

Most of the time the name of the theme function will be the name of the *.tpl.php file, without the .tpl.php ending and with underscores instead of the hyphens. But there is a catch if the template file gets selected on the base of template suggestions, as the preprocess function can only be implemented for the base name, not for the additional suggestions! (The suggestions for alternate template files are added in preprocess functions themselves.)

Your current example is one of those cases, as content-field-field_transmission_make_model.tpl.php is such a suggestion, with the base name being content-field.tpl.php, and the corresponding theme function being content_field. So you would have to implement a preprocess function named yourThemeName_preprocess_content_field(&$variables), and within that inspect the available entries in the $variables array to check if you are actually called for the 'field_transmission_make_model', and not for a completely different CCK field, e.g.:

function yourThemeName_preprocess_content_field(&$variables) {
  // Are we called for the right field?
  if ('field_transmission_make_model' == $variables['field_name']) {
    // Yes, add/manipulate entries within the variables array
    $variables['new_entry'] = 'A useless new variable';
    $variables['label'] = 'A useless change of the existing label variable';
  }
}

(Note: Untested code, beware of typos)

After this, there should be a new variable $new_entry being available in your template file, and the content of the $label variable should have changed (all top level entries within the $variables array will be turned into separate variables for the template file, named after the array index).

---

As for your second question, the basic usage of preprocess functions is the same for all template files, but be aware:

• Preprocess functions are only available for theme calls that use *.tpl.php files, not for theme functions
• The content of the $variables array varies heavily, depending on what gets themed
• Other modules might implement the preprocess functions as well, and they will be called one after another, so if you want to change something that gets added by another module, you can only do so if your implementation gets called after that (which will be no problem in your case, as implementations within a theme are called after all implementations within modules - just wanted to mention that there can be many implementations at once)

Solution 2

In order to figure out what our preprocessing function should be named, we need to know what template file or theme function some output comes from, and one great way to do this is by using the theme developer module.

Here is a video which explains it in detail - http://buildamodule.com/video/drupal-theming-essentials-template-files-theme-function-overrides-and-preprocessing-functions-how-to-use-simple-preprocessing-functions

Comments

[Jamison Dance]

Thanks, that helps my understanding a lot. I was under the mistaken impression that the preprocessor functions could be specific to templates. Is there much of a performance hit for implementing a preprocessor function just to change one node type or content field? It just seems inefficient to call the preprocess function for every node or field or whatever when you only want to add a new variable fro one specific type of node.

[Henrik Opel]

@Jergason: While there sure is a little overhead associated, a function call in itself costs almost nothing, as long as it doesn't do heavy processing (You'd need hundreds of thousand calls to make it measurable in milliseconds). In my experience, the advantage of keeping the template files clean of 'advanced' processing logic is well worth it (especially if one day you want/need to split the workload and pass them to a designer).