Official Views 2 documentation exists as part of the Advanced Help module. A request has been filed to add this tutorial to Views -- see http://drupal.org/node/495846

The Advanced Help module is currently the only source of documentation for Views 3 theming.

For those who are familiar with theming in Views 1, the process in Views 2 may seem overwhelming at first. Unlike Views 1, in which you might have a single template file for each view, Views 2 allows you to have a template for each facet of each view, which it then assembles into a single presentation.

Step 1: Identifying the Views Template Theme Layers

Edit your view. Pick the display (e.g. Block, Page, etc.) you wish to theme. Under the "Basic settings" section, click on Theme Information.

A list of template files will be displayed, in the following order:

  1. Display output: This controls the structure of the overall view, including the position of and code around the view administrative links, header, exposed filters, pager, "more" link, footer and feed icon. This template also controls the position of and code around the primary view content, empty content, and attached views.
  2. Style output: This controls the structure of this particular view display's style, e.g. HTML List, Table, Unformatted, etc. This includes the view title and the code surrounding each row (item in your view) of the given style.
  3. Row style output: This controls the internal structure of each row (item in your view), including the label and the content for each field.
  4. Fields: There will be one entry for each field in your display, allowing you to control the structure and code for each. If your row style is set to "Node," there won't be any field entries, and the view will use the node's template file instead.

If you have a separate admin theme and are not using the most recent version of Views (6.x-2.6), the information displayed in this section will be for your admin theme, so you'll need to switch it to your main theme for the duration of your views theming.

Step 2: The Template Inheritance Process

What do the templates listed in bold mean? Theme Information lists all of the possible template files you could have for a given theme, from the general to the specific. In a similar method to the way in which precedence is given to core templates with the most specific file names, Views 2 gives precedence to the most specifically named templates. The templates listed in bold, then, are the templates currently in effect for your view.

For example, let's say you had three views, called alpha, beta and gamma. The file views-view.tpl.php would control the overall display output (see above) for all three views. If you then created a file called views-view--alpha.tpl.php, that would apply to your alpha view display, but beta and gamma would still be controlled by the overall template.

You could subsequently create templates for each display within your view:

  • The files views-view--alpha--page.tpl.php and views-view--alpha--block.tpl.php, for instance, would control those two types of displays for the alpha view.
  • The file views-view--page.tpl.php would control all views with a "page" display.
  • The file views-view--page-1.tpl.php would control the display on the first page of all views (for those that use a pager), while views-view--alpha--page-1.tpl.php would override that display for the alpha view.

One way to think of the template files is that each "level" creates input variables for the level above it—field templates get fed into row style templates, which are then fed into style templates, which are then fed into the overall display template.

This precedence based on specificity is the same for each set of templates.

Step 3: Creating Your Template File

Follow the link for each type of output or field to see the current template file. Copy and paste this code into a new file, naming it with the level of specificity you desire. You can create a "views" subfolder of your theme to keep all of your views template files if you like.

For instance, if your beta view's title field is currently being controlled with the general template views-view-field.tpl.php, you could copy the code from that template and create a new file—views-view-field--beta--title.tpl.php—to control the display only of that field within the beta view.

It's a good idea to select one of your displays (see Step 1) before determining the name of your template file. Otherwise, you might create a template like views-view-field--taxonomy-term--default--tid.tpl.php, based on the "default" display, which would never actually get displayed in your page, block, etc.

Once you have your new file, you can modify the output as you like. For instance, <?php print $output; ?> could be modified to <h3><?php print $output; ?></h3>.

Step 4: Identifying Your Template Variables

For simple templates, you can skip this step. If you want to systematically set, reorder and modify the display of individual variables within your templates, however, you'll need to identify and insert your view's variables.

The default template code will have some general variables listed in comments at the top of the template, which can be useful as a starting point. To see all of your specific view's variables, you can place the following code in a high-level template (like views-view.tpl.php or views-view--alpha.tpl.php for a view named alpha):

<?php
 print print_r(array_keys(get_defined_vars()), 1);
  // If you have devel.module installed, comment the line above and uncomment the line below
  // dsm(array_keys(get_defined_vars())); 
?>

Each array key is the name of a variable, so an array key named "foo" could be inserted into the template as <?php print $foo; ?>.

Field Variables

If your row style is set to fields, you'll have a single "fields" variable. To see the list of your field names, put the following code in a high-level template (like views-view.tpl.php or views-view--alpha.tpl.php for a view named alpha):

<?php
  print '<pre>' . htmlentities(print_r($rows, 1)) . '</pre>';
  // If you have devel.module installed, comment the line above and uncomment the line below
  // dsm(array_keys($fields)); 
?>

Once you have your fields, you can take a look at the comments at the top of the views-view-fields.tpl.php file to see what attributes of each field you can extract. To insert the specific fields, use the syntax <?php print $fields['foo']->content; ?>, where "foo" is the name of a field.

For instance, let's say you have a content type named "bar" that has a title and a link field, and you want to create a view of the titles linked to the value in the link field. You could create a file named views-view-fields--bar.tpl.php with the following code:

<a href="<?php print $fields['field_boo_url_url']->content; ?>"><?php print $fields['title']->content; ?></a>

If you have optional fields, you may want to check to see if the value exists:

<?php 
  if ($fields['field_boo_url_url']->content) {
    print '<a href="' . $fields['field_boo_url_url']->content . '">' . $fields['title']->content . '</a>';
  }
?>

You can create your own variables for your templates through the use of preprocess functions. For instance, you might use this method to set up logic outputting different variables depending on field values or other attributes.

Step 5: Updating Your View

After creating your file, go back to your view. If the theming information screen is still open, follow the link at the top that says "Back to theming information."

At the bottom of the theming information section, click "Rescan template files." This will clear the theme registry, and the template files listed in bold should change to reflect your new templates. If you have an administrative theme, you'll need to switch to your presentation theme to see what's in effect (see Step 1, above).

Finally, click "Ok," save your view and view it to see the updates. If you have also created styles related to your new view templates, you may also need to clear your cache and/or turn off optimizing CSS files at /admin/settings/performance.

Resources

Group 42 has a more visual guide to Views 2 theming; much of "Identifying Your Template Variables" above was drawn from this article. There is also a Spanish translation.

Views online help has a guide to using Views templates that goes into more detail about using template and field variables.

Comments

xqi’s picture

if you need access other fields in your field template, you can access them by

echo $row->{$view->field['FIELD_ID']->field_alias};

You can see more examples here http://xinspace.com/drupal-views-theming-access-other-fields-value-in-yo...

the credits go to vatavale at http://drupal.org/node/763620

Steel Rat’s picture

I haven't figured this out yet, but is it possible to affect row style output with Table formatting? I want to keep the clickable/sortable column headers, but desperately need to color rows based on the value of a field. So far the only way I've seen to get to that level is by using "unformatted" or something other than table.

Help!

davedpss’s picture

I have tried copying the code out of the default theme being used (for display, style and row) and then creating a new tpl file using a more specific name. When I click "Rescan Template files" the new files I have created are now bold. I then click ok and if I go back and to theme information again, the default tpl files are bold again and not the files I created. I have tried doing a save before I go back to check but the defaults are always bold again and none of the changes I made have taken effect.

Any help on this would be greatly appreciated. Thanks - Dave.

hmdnawaz’s picture

how to display the output of the view?

Ahmad Nawaz
Acquia Certified Developer
Email: hmdnawaz@gmail.com
Skype: hmdnawaz

agcilantro’s picture

I am unable to find the block template that is being used by my view. Where Is the views-view--block.tpl.php located, in the views folder, the theme folder or the modules/system folder?

hmdnawaz’s picture

If you want it for the specific view then you will create it inside the your theme folder.

Ahmad Nawaz
Acquia Certified Developer
Email: hmdnawaz@gmail.com
Skype: hmdnawaz

hmdnawaz’s picture

If you want it for the specific view then you will create it inside your theme folder.

Ahmad Nawaz
Acquia Certified Developer
Email: hmdnawaz@gmail.com
Skype: hmdnawaz

cigotete’s picture

well, just for note that my only way to show the array information was

 print_r($row); 
Shinzon’s picture

Is there any way to get url of title? Something like this, but these are not working

<a href="<?php print $fields['title_url']->content; ?>"><?php print $fields['title']->content; ?></a>

<a href="<?php print $fields['title_url_url']->content; ?>"><?php print $fields['title']->content; ?></a>

compsyguy’s picture

When you create your template file you have to change the underscores to dashes (-).

I kept getting a file not found error when scanning for the template files.

dakke’s picture

The view is set to fields (informatted) and I try to get the field variables using:

<?php
  print '<pre>' . htmlentities(print_r($rows, 1)) . '</pre>';
  // If you have devel.module installed, comment the line above and uncomment the line below
  // dsm(array_keys($fields));
?>

Devel is installed hence the code ought to be

<?php
  print //'<pre>' . htmlentities(print_r($rows, 1)) . '</pre>';
  // If you have devel.module installed, comment the line above and uncomment the line below
   dsm(array_keys($fields));
?>

Yet nothing is printed and no field variables are seen.