Theming a single field in a Views 3 template

Last updated on
15 June 2018

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

Follow these steps to change the design of a single field in a view, using template suggestions.

Helpful modules

To make it easier to understand and troubleshoot your template code, install and enable both the Devel and Theme Developer modules on your test site.

WARNING: these should not be used on LIVE sites as they are for development only and will slow your site's performance.

HELPFUL HINTS: The Theme Developer module is more complicated to install, so you can install only the Devel module, if you just want to be able to print out the code names given to your field in Drupal.

Watch the video tutorial by the devel modules' creator or the Lynda.com video to get a better understanding of how these modules might make it easier for you to theme Drupal 7.

Copy the template file into your theme folder

Copy the single-field template from the views module (probably found at root/sites/all/modules/views/theme/views-view-field.tpl.php) into the folder for your subtheme (like root/sites/all/themes/mytheme). You can also find the code for this template on the Drupal API site.

Theming a field in a non-Views display

If you want to theme this same field in non-view displays on your site, such as a full page view, you will also need to copy the single-field template from drupal core (at root/modules/field/theme/field.tpl.php) into that same subtheme folder. The Drupal API site explains the code for this template.

Rename the copied template file

Rename the copied views-view-field.tpl.php template file in your theme folder to views-view-field--field-fieldname.tpl.php.

  1. Using a double-hyphen after "field" tells Drupal to use your theme suggestion, instead of the default Views theme, to display this specific field.
  2. Fields created via the UI have a name prefixed with "field" which is why we write field--field-fieldname  however, fields already included in core such as the user's profile picture are not prefixed. So overriding the template will work with views-view-field--picture.tpl.php
  3. Notice that you do NOT use underscores for your field's name.
  4. To obtain a list of all file names that can be used to theme a view, open up your specific view display and under the Advanced section select Theme: Information.
  5. Drupal's helpful documentation explains how to name files so you can override core templates with your own displays.

Configure theme debugging

Turn off caching

Whenever you theme a view, always turn off caching in Views, so that you see the most current theme code (and not saved copies of earlier code).

Turn on debugging

To change the way your field's data is displayed, you need to change the one line in your template file that prints out data: <?php print $output; ?>.

Remove the print command and add de-bugging code, like this:

<?php 
  /* Your code goes here. */
  if($output) {
    dpm($row);
  }
  else { }   
?>

The Devel module gives us the dpm() function, so we can find the names (or aliases) that Views and Drupal use to describe a field and its elements. We use $row instead of $output because we want to see the key data structures of our field, and not the final, already-styled html code.

Find the names of the field and its elements

Now that you've enabled debugging, open the View you are theming in a web browser. The message area of this view shows a list of divs that start with the phrase "... (Object) stdClass". Each expandable Object div is one "row" from this view.

Find the field alias

In the debugging message area of your View, click on and expand any Object div.

To find what the template documentation calls your "field_alias", look for this pattern:

  • starts with the words "field_field" (notice that the alias DOES use underscores, unlike the field name)
  • ends with the phrase "(Array, 1 element)"
    • If a row does not include any data for your field, there will be "0 elements" in the ending phrase.
    • Likewise, if you have multiple values for this field, the ending phrase will show a number higher than one.

Update your debug code

Open up the template file you are editing and change it to show only your field alias and not the entire row, like this:

<?php 
  /* Your code goes here. */
  if($output) {
    dpm($row->field_field_fieldname);
  }
  else { }   
?>

Now, instead of Object divs, the View in your web browser shows a list of Array divs that start with the phrase "... (Array, 0 elements)". Only those Array divs with more than zero (0) elements have content for this field.

Find the field's array elements

In the debugging message area of your View, click on and expand a non-zero Array div.

For simple fields (such as Text, Long text, and Email), the array will expand into a nested list like this:

  • 0
    • rendered
      • #markup
    • raw
      • safe_value
  • 1
  • 2

More complicated fields (such as link), will look differently, perhaps like this:

  • 0
    • rendered
      • #element
        • url
        • title
    • raw
      • url
      • title
  • 1

Add your field's array elements into your template

Update your debug code, again

Before adding the actual styles into the template code, test each piece of data to make sure you can call it correctly.

For example:

...

MORE instructions go here.

Help improve this page

Page status: No known problems

You can: