Drupal: Override output of taxonomy term page per vocabulary

Occasionally it is necessary to alter the output that is generated when a user clicks on a taxonomy term link. Generating custom mark-up for all taxonomy term pages is a simple two step process:

  1. Copy page.tpl.php into your theme folder and rename it page--taxonomy.tpl.php. 

  2. Clear all caches.

But what if you want unique mark-up for terms belonging to a particular vocabulary? Still pretty simple, but it does involve a couple more steps:

Drupal 7:

  1. Find the machine name for your vocabulary. (Hint: go to admin/structure/taxonomy and click "edit" next to the vocabulary. The vocabulary's machine name will appear in the URL).

  2. Copy page.tpl.php into your theme folder and rename it page--vocabulary--[machine name].tpl.php. Of course replace "[machine name]" with the actual machine name. If page.tpl.php doesn't already exist in your theme folder, grab a copy from your base theme, if you are using one, or the modules/system folder. (If you are customizing more than one vocabulary, just repeat this step for each.)

  3. Open template.php in your theme folder (create it if it doesn't exist) and paste in the function below. Replace "THEME" with the name of your theme. 

    function THEME_preprocess_page(&$vars) {
      if (arg(0) == 'taxonomy' && arg(1) == 'term' && is_numeric(arg(2))) {
        $term = taxonomy_term_load(arg(2));
        $vars['theme_hook_suggestions'][] = 'page__vocabulary__' . $term->vocabulary_machine_name;
      }
    }

    By adding the code above, you are "suggesting" a new template be used that deals specifically with the vocabulary being loaded.

  4. Clear all caches.

Note: There are more straightforward methods for making minor adjustments, such as altering the page title (see Drupal's drupal_set_title function) or hiding a region (see the Context module). The method above, which overrides page.tpl.php, is for when you want to make major changes to the template.