On this page
- Theme debug mode
- Custom Theme Hook Suggestions
- Default Theme Hook Suggestions in Core
- block--[region|[module|--delta]].tpl.php
- comment--node-[type].tpl.php
- comment-wrapper--node-[type].tpl.php
- field--[type|name[--content-type]|content-type].tpl.php
- forums--[[container|topic]--forumID].tpl.php
- html.tpl.php
- maintenance-page--[offline].tpl.php
- node--[type|nodeid].tpl.php
- page--[front|internal/path].tpl.php
- How Drupal determines page theme hook suggestions based on path
- poll-results--[block].tpl.php
- poll-vote--[block].tpl.php
- poll-bar--[block].tpl.php
- profile-wrapper--[field].tpl.php
- region--[region].tpl.php
- search-results--[searchType].tpl.php
- search-result--[searchType].tpl.php
- taxonomy-term--[vocabulary-machine-name|tid].tpl.php
- Add a page.tpl.php depending on content type.
- Cache issue
Template (theme hook) suggestions
Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites
A theme hook suggestion is an alternate template (.tpl.php) file that you have created to override the base or original template file.
For Drupal 8, see Twig template naming conventions.
Theme debug mode
As of Drupal 7.33, Drupal core has a theme debug mode that can be enabled and disabled via the theme_debug
variable and is very helpful when working with template suggestions.
Custom Theme Hook Suggestions
Custom suggestions beyond the ones listed below can be created. See the page Working with template suggestions.
Default Theme Hook Suggestions in Core
block--[region|[module|--delta]].tpl.php
base template: block.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:
- block--module--delta.tpl.php
- block--module.tpl.php
- 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--block--1.tpl.php" would be used for the first user-submitted block added from the block administration screen since it was created by the block module with the id of 1. "region" will take effect for specific regions. An example of a region-specific template would be "block--sidebar_first.tpl.php".
If you had a block created by a custom module called "custom" and a delta of "my-block", the theme hook suggestion would be called "block--custom--my-block.tpl.php."
Also one more example with Views, if you have a block created by views with a view name "front_news" and display id "block_1" then the theme hook suggestion would be: block--views--front-news-block-1.tpl.php (notice, when you have underscores in a display id or in a view name - you have to transform them into a single dash)
Be aware that module names are case sensitive in this context. For instance if your module is called 'MyModule', the most general theme hook suggestion for this module would be "block--MyModule.tpl.php."
See block.tpl.php in the Drupal API documentation for more information.
comment--node-[type].tpl.php
base template: comment.tpl.php
Support was added to create comment--node-type.tpl.php files, to format comments of a certain node type differently than other comments in the site. For example, a comment made on an article-type node would be "comment--node-article.tpl.php".
See comment.tpl.php in the Drupal API documentation for more information.
comment-wrapper--node-[type].tpl.php
base template: comment-wrapper.tpl.php
Similar to the above but for the wrapper template.
See comment-wrapper.tpl.php in the Drupal API documentation for more information.
field--[type|name[--content-type]|content-type].tpl.php
base template: field.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:
- field--field-name--content-type.tpl.php
- field--content-type.tpl.php
- field--field-name.tpl.php
- field--field-type.tpl.php
Note that underscores in a Field's machine name are replaced by hyphens. Also remember to include "field-" in custom field names, e.g: field--field-phone.tpl.php.
See field.tpl.php in the Drupal API documentation for more information.
forums--[[container|topic]--forumID].tpl.php
base template: forums.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:
For forum containers:
- forums--containers--forumID.tpl.php
- forums--forumID.tpl.php
- forums--containers.tpl.php
For forum topics:
- forums--topics--forumID.tpl.php
- forums--forumID.tpl.php
- forums--topics.tpl.php
See forums.tpl.php in the Drupal API documentation for more information.
html.tpl.php
base template: html.tpl.php
The following are some examples of how you may override the base template:
- html--internalviewpath.tpl.php
- html--node--id.tpl.php
See html.tpl.php in the Drupal API documentation for more information.
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.
See maintenance-page.tpl.php in the Drupal API documentation for more information.
node--[type|nodeid].tpl.php
base template: node.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:
- node--nodeid.tpl.php
- node--type.tpl.php
- node.tpl.php
See node.tpl.php in the Drupal API documentation for more information.
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 is 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 Pathauto module uses 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:
- page--node--edit.tpl.php
- page--node--1.tpl.php
- page--node.tpl.php
- page.tpl.php
Also see page.tpl.php in the Drupal API documentation for more information.
How Drupal determines page theme hook suggestions based on path
Here is another explanation based on the theme_get_suggestions() function:
The list of possible templates for a given page is generated by Drupal through the theme_get_suggestions() function, which is called by the template_preprocess_page() function.
The Drupal path of the page is first broken up into its components. As mentioned above, the Drupal path is not any of its aliases: there is one and only one Drupal path for a page. For the examples "http://www.example.com/node/1/edit" and "http://www.example.com/mysitename?q=node/1/edit", the Drupal path is node/1/edit, and its components are "node", 1, and "edit".
Next, the prefix is set to "page". Then, for every component, the following logic is followed:
- If the component is a number, add the prefix plus "__%" to the list of suggestions.
- Regardless of whether the component is a number or not, add the prefix plus "__" plus the component to the list of suggestions.
- If the component is not a number, append "__" plus the component to the prefix.
After the list of components is iterated through, if the page is the front page (as set through "Administration > Configuration > System > Site information."), then "page__front" is added to the list of suggestions.
Note that eventually, to turn a suggestion into an actual file name, "__" gets turned into "--", and ".tpl.php" gets appended to the suggestion. Thus, for node/1/edit, we get the following list of suggestions:
- page.tpl.php (this is always a suggestion)
- page--node.tpl.php (and prefix is set to page__node)
- page--node--%.tpl.php
- page--node--1.tpl.php (prefix is not changed because the component is a number)
- page--node--edit.tpl.php (and prefix is set to page__node__edit)
- page--front.tpl.php (but only if node/1/edit is the front page)
When the page is actually rendered, the last suggestion is checked. If it exists, that suggestion is used. Otherwise the next suggestion up is checked, and so on. Of course, if none of the overriding suggestions exist, page.tpl.php is the final suggestion. This also explains why page--front.tpl.php, if it exists, overrides any other suggestion for the front page: it is always the last suggestion for the page designated as the front page.
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".
See poll-results.tpl.php in the Drupal API documentation for more information.
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.
See poll-vote.tpl.php in the Drupal API documentation for more information.
poll-bar--[block].tpl.php
base template: poll-bar.tpl.php
Same as poll-vote--[block].tpl.php but for generating individual bars.
See poll-bar.tpl.php in the Drupal API documentation for more information.
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".
See profile-wrapper.tpl.php in the Drupal API documentation for more information.
region--[region].tpl.php
base template: region.tpl.php
The region template is used when a page region has content, either from the Block system or a function like hook_page_build(). Possible region names are determined by the theme's .info file.
See region.tpl.php in the Drupal API documentation for more information.
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.
See search-results.tpl.php in the Drupal API documentation for more information.
search-result--[searchType].tpl.php
base template: search-result.tpl.php
The same as above but for individual search results.
taxonomy-term--[vocabulary-machine-name|tid].tpl.php
base template: taxonomy-term.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:
- taxonomy-term--tid.tpl.php
- taxonomy-term--vocabulary-machine-name.tpl.php
- taxonomy-term.tpl.php
Note that underscores in a vocabulary's machine name are replaced by hyphens.
See taxonomy-term.tpl.php in the Drupal API documentation for more information.
Add a page.tpl.php
depending on content type.
In Drupal 7, you do this by having this code in the function THEME_preprocess_page
(where THEME
is the name of the theme) in the theme's template.php
.
function THEME_preprocess_page(&$variables) {
if (isset($variables['node']->type)) {
// If the content type's machine name is "my_machine_name" the file
// name will be "page--my-machine-name.tpl.php".
$variables['theme_hook_suggestions'][] = 'page__' . $variables['node']->type;
}
}
Add the if-statement at the end if this function already exists in the theme's template.php
, otherwise, add the functions.
Cache issue
When working with theme hook suggestion, there is a possibility that Drupal use its cache rather than the new templates as suggested. Remove the cache if you experience this problem. To clear the cache, choose one of the methods described in Clearing Drupal's cache.
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