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:
- 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.
- 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.
- Row style output: This controls the internal structure of each row (item in your view), including the label and the content for each field.
- 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
andviews-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), whileviews-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
access other fields in your field template
if you need access other fields in your field template, you can access them by
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
I haven't figured this out
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!
theme tpl does not stay selected
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.
how to display the output of the view?
how to display the output of the view?
Ahmad Nawaz
Acquia Certified Developer
Email: hmdnawaz@gmail.com
Skype: hmdnawaz
template suggestions for overriding block views
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?
You will create it.
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
You will create it.
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
well, just for note that my
well, just for note that my only way to show the array information was
href of title
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>
If view name contains underscores (_)
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.
Can't get field variables to show
The view is set to fields (informatted) and I try to get the field variables using:
Devel is installed hence the code ought to be
Yet nothing is printed and no field variables are seen.