Last updated October 24, 2014. Created on March 11, 2011.
Edited by camorim, Carolyn. Log in to edit this page.

Template suggestions:

What's a template suggestion? It's an alternate template (.tpl.php) file that you have created to override the base or original template file. Suggestions only work when they are placed in the same directory as the base templates. In other words, if you want comment-blog.tpl.php to display in your browser, comment.tpl.php also needs to exist inside your theme and the two files must be in the same directory.

Custom suggestions beyond the ones listed below can be created. See the page Working with template suggestions.

Note: There is a bug which prevents derivative template files from being detected if the base template file is not also present. See #279573: Themes can't use node-story.tpl.php without node.tpl.php for more information.

block-[region|[module|-delta]].tpl.php
base template: block.tpl.php

Suggestions made based on these factors in this order:

  1. block-module-delta.tpl.php
  2. block-module.tpl.php
  3. block-region.tpl.php

"module" being the name of the module and "delta", the internal id assigned to the block by the module. For example, "block-user-1.tpl.php" would be used for the default user navigation block since it was created by the user module with the id of 1. "region" will take effect for specific regions.

comment-[type].tpl.php
base template: comment.tpl.php

Support was added to create comment-type.tpl.php files, to format comments of a certain node type differently than other comments in the site. Similar to node-[type].tpl.php but for comments.

comment-wrapper-[type].tpl.php
base template: comment-wrapper.tpl.php

Similar to the above but for the wrapper template.

forums-[[container|topic]-forumID].tpl.php
base template: forums.tpl.php

Template suggestions added based on these factors, in this order.

For forum containers:

  1. forums-containers-forumID.tpl.php
  2. forums-forumID.tpl.php
  3. forums-containers.tpl.php

For forum topics:

  1. forums-topics-forumID.tpl.php
  2. forums-forumID.tpl.php
  3. forums-topics.tpl.php
maintenance-page-[offline].tpl.php
base template: maintenance-page.tpl.php

This applies when the database fails. Useful for presenting a friendlier page without error messages. Theming the maintenance page must be properly setup first.

node-[type].tpl.php
base template: node.tpl.php

In Drupal 7, templates for specific content types are created slightly different than in Drupal 6.

  • Drupal 6: node-mytype.tpl.php
  • Drupal 7: node--mytype.tpl.php

See node.tpl.php in the Drupal API documentation for more information.

Note that in order to override the template for a specific node type, the theme must also implement the base node.tpl.php file. If this file is omitted, the theme will not detect the presence of node-[type].tpl.php files.

page-[front|internal/path].tpl.php
base template: page.tpl.php

The suggestions are numerous. The one that takes precedence is for the front page. The rest are based on the internal path of the current page. Do not confuse the internal path to path aliases which are not accounted for. Keep in mind that the commonly used Path auto module works its magic through path aliases.

The front page can be set at "Administration > Configuration > System > Site information." In Drupal 6, at "Administrator > Site configuration > Site information." Anything set there will trigger the suggestion of "page-front.tpl.php" for it.

The list of suggested template files is in order of specificity based on internal paths. One suggestion is made for every element of the current path, though numeric elements are not carried to subsequent suggestions. For example, "http://www.example.com/node/1/edit" would result in the following suggestions:

  1. page-node-edit.tpl.php
  2. page-node-1.tpl.php
  3. page-node.tpl.php
  4. page.tpl.php
poll-results-[block].tpl.php
base template: poll-results.tpl.php

The theme function that generates poll results are shared for nodes and blocks. The default is to use it for nodes but a suggestion is made for rendering them inside block regions. This suggestion is used by default and the template file is located at "modules/poll/poll-results-block.tpl.php".

poll-vote-[block].tpl.php
base template: poll-vote.tpl.php

Similar to poll-results-[block].tpl.php but for generating the voting form. You must provide your own template for it to take effect.

poll-bar-[block].tpl.php
base template: poll-bar.tpl.php

Same as poll-vote-[block].tpl.php but for generating individual bars.

profile-wrapper-[field].tpl.php
base template: profile-wrapper.tpl.php

The profile wrapper template is used when browsing the member listings page. When browsing specific fields, a suggestion is made with the field name. For example, http://drupal.org/profile/country/Belgium would "suggest profile-wrapper-country.tpl.php".

search-results-[searchType].tpl.php
base template: search-results.tpl.php

search-results.tpl.php is the default wrapper for search results. Depending on type of search different suggestions are made. For example, "example.com/search/node/Search+Term" would result in "search-results-node.tpl.php" being used. Compare that with "example.com/search/user/bob" resulting in "search-results-user.tpl.php". Modules can extend search types adding more suggestions of their type.

search-result-[searchType].tpl.php
base template: search-result.tpl.php

The same as above but for individual search results.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

AmicableNinja’s picture

For details on node theming (node-[type].tpl.php), see "Theming nodes by content type"

unleet’s picture

Note that in order to override the template for a specific node type, the theme must also implement the base node.tpl.php file. If this file is omitted, the theme will not detect the presence of node-[type].tpl.php files.

This was a limitation in Drupal 6, but I believe it is no more in Drupal 7.