All your variable are belong to us

Preprocess functions are designed to keep logic seperate from the markup that's inside template files. They also allow us access to a lot of data that we can print inside our tipplefips (tpl.php files). Take a preprocess function for node.tpl.php for example: this function has access to read and alter it’s $variables array, which (in this case) contains all the node’s field data. Suddenly that date field that you wanted to print at the top of your tpl file is pretty easy to get at.

So to get started, grab a virgin copy of node.tpl.php from modules/node and copy it to your theme’s templates directory. You'll also need to download and install the Devel module. Then add these lines to your theme’s template.php file.

/**
 * Preprocess function for node.tpl.php.
 */
function YOURTHEMESNAME_preprocess_node(&$vars) {
  kpr($vars);
}

In the above example I have shortened the preprocess argument array to “$vars” (this just makes it a little quicker to read and write), and I have used the Devel module’s kpr() function to print all the data we have access to. Once you clear Drupal’s cache load up a node page from your Drupal installation, and at the top of the page you’ll be greeted with a Krumo output of your $vars array.

Now there is a tonne of information in there as it literally has every part of data associated with your node. So it’s just a matter of drilling down into each array to find the exact piece of info you are looking for:

You can then add a line to your preprocess function so you can print things out in a nice neat way inside your tpl file. Something like this:

$vars[‘description’] = $vars[‘field_description’][0][‘safe_value’];

Anything you add to the $vars array will be available to print in your node.tpl.php file. So based on the example above, we can just add the following line to our tpl file to print the variable:

<?php print $description ?>

Keep in mind that each field will have several ways to output it’s data - in the example above the description field has both a ‘value’ and a ‘safe_value’ - always use the safe versions as these have been checked for any potentially harmful code.

The Search Krumo module will add a handy search field above the Krumo output which will speed up finding the exact variable you are after.

What to call your preprocess functions?

Drupal 7’s theme engine will allow preprocess functions for almost every tpl file that gets rendered. So it’s actually fairly simple to figure out what they are called using a simple formula illustrated below:

/**
 * Preprocess function for field.tpl.php.
 */
function YOURTHEMESNAME_preprocess_field(&$vars) {
}

/**
 * Preprocess function for page.tpl.php.
 */
function YOURTHEMESNAME_preprocess_page(&$vars) {
}

/**
 * Preprocess function for taxonomy-term.tpl.php.
 */
function YOURTHEMESNAME_preprocess_taxonomy_term(&$vars) {
}

Each & every preprocess function will have a $vars argument, and printing that with kpr() will show you exactly what data you have access to.

What if something I need isn’t in there?

There will be many cases where you’ll look inside your $vars array to see a particular piece of information isn’t there. Thankfully there are other ways of obtaining the data we need!

Take a user reference field attached to a node for example. We may want to print the user’s name at the top of our node, but after looking inside the array we can only see a value for uid. In this case we can do something like the below:

$user = user_load($vars[‘field_user’][0][‘uid’]);
$vars[‘users_name’] = check_plain($user->name);

In the above example the user_load() function will return the complete user object which will have the value of the user’s name, I have then wrapped the output of $user->name in a check_plain function to make sure it's safe to print out. Placing this code inside a preprocess function is best practice as it keeps your tpl file nice and neat (calling functions inside a tpl file is a big no no).

There are quite a few of these x_load type functions in Drupal, some notable ones being node_load(), taxonomy_term_load() and entity_load(). Each will take a nid,uid,tid, etc, and return the complete object filled with lots of juicy data you can easily print out in your tpl files.

And what about function inheritance?

Most modules & base themes will implement their own preprocess functions for various template files. The load order of these functions will often affect what data you have access to in your theme’s preprocess functions. Generally speaking the preprocess functions are executed as follows:

1. The module
These will generally be found in a MODULENAME.theme.inc file.

2. The base theme (if you are using one)
These will be inside the theme’s template.php file.

3. Your theme

So anytime a module or base theme adds to or alters the $vars array, your theme’s preprocess function will pick up that change. If some piece of data is being altered along the line, or you can’t tell where something inside your $vars array is coming from, you can always poke around in the appropriate file(s) to find out exactly what is happening. Preprocess functions inside modules and base themes also serve as great examples of how to get the job done properly.