+3  A: 

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)
Henrik Opel
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.
Jergason
@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).
Henrik Opel

related questions