On this page
- Helpful modules
- Copy the template file into your theme folder
- Theming a field in a non-Views display
- Rename the copied template file
- Configure theme debugging
- Turn off caching
- Turn on debugging
- Find the names of the field and its elements
- Find the field alias
- Update your debug code
- Find the field's array elements
- Add your field's array elements into your template
- Update your debug code, again
- MORE instructions go here.
Theming a single field in a Views 3 template
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
.
- Using a double-hyphen after "field" tells Drupal to use your theme suggestion, instead of the default Views theme, to display this specific field.
- 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 withviews-view-field--picture.tpl.php
- Notice that you do NOT use underscores for your field's name.
- 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.
- 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
- rendered
- 1
- 2
More complicated fields (such as link), will look differently, perhaps like this:
- 0
- rendered
- #element
- url
- title
- #element
- raw
- url
- title
- rendered
- 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
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion