Last updated April 1, 2014. Created by Carolyn on March 11, 2011.
Edited by gisle, Heihachi88, rooby, polishyourimage. Log in to edit this page.

A theme hook suggestions is an alternate template (.tpl.php) file that you have created to override the base or original template file.

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:

  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--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 in to 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."

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".

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

Similar to the above but for the wrapper template.

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:

  1. field--field-name--content-type.tpl.php
  2. field--content-type.tpl.php
  3. field--field-name.tpl.php
  4. 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.

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:

  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
html.tpl.php
base template: html.tpl.php

The following are some examples of how you may override the base template:

  1. html--internalviewpath.tpl.php
  2. 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.

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:

  1. node--nodeid.tpl.php
  2. node--type.tpl.php
  3. 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 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 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:

  1. page--node--edit.tpl.php
  2. page--node--1.tpl.php
  3. page--node.tpl.php
  4. 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:

  1. If the component is a number, add the prefix plus "__%" to the list of suggestions.
  2. Regardless of whether the component is a number or not, add the prefix plus "__" plus the component to the list of suggestions.
  3. 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:

  1. page.tpl.php (this is always a suggestion)
  2. page--node.tpl.php (and prefix is set to page__node)
  3. page--node--%.tpl.php
  4. page--node--1.tpl.php (prefix is not changed because the component is a number)
  5. page--node--edit.tpl.php (and prefix is set to page__node__edit)
  6. 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".

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".

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.

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.

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:

  1. taxonomy-term--tid.tpl.php
  2. taxonomy-term--vocabulary-machine-name.tpl.php
  3. taxonomy-term.tpl.php

Note that underscores in a vocabulary's machine name are replaced by hyphens.

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(&$vars, $hook) {
  if (isset($vars['node']->type)) {
    // If the content type's machine name is "my_machine_name" the file
    // name will be "page--my-machine-name.tpl.php".
    $vars['theme_hook_suggestions'][] = 'page__' . $vars['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.

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

Comments

I'm working on a custom module and I want to keep my template file in my module directory (as opposed to a theme directory)

This approach worked for me: http://www.metachunk.com/blog/adding-module-path-drupal-7-theme-registry...

Use the following:

For D6:

<?php
function themeName_preprocess_page(&$vars, $hook) {
  if (isset(
$vars['node'])) {
  
// If the node type is "blog" the template suggestion will be "page-blog.tpl.php".
  
$vars['template_files'][] = 'page-'. str_replace('_', '-', $vars['node']->type);
  }
}
?>

For D7:

<?php
function themeName_preprocess_page(&$vars, $hook) {
  if (isset(
$vars['node'])) {
 
// If the node type is "blog" the template suggestion will be "page--blog.tpl.php".
  
$vars['theme_hook_suggestions'][] = 'page__'. str_replace('_', '--', $vars['node']->type);
  }
}
?>

Perhaps Drupal 7 changed the name handling, because I did not need to do the string replacement. Otherwise this worked perfectly. The behavior that I saw with Drupal 7.2 was that the theme_hook_suggestions variables contain all underscores, and that those underscores are all translated to hyphens when it looks to pick up the template file. Here's the code that worked for me:

<?php
function themeName_preprocess_page(&$vars, $hook) {
  if (isset(
$vars['node'])) {
   
// If the node type is "blog_madness" the template suggestion will be "page--blog-madness.tpl.php".
   
$vars['theme_hook_suggestions'][] = 'page__'. $vars['node']->type;
  }
}
?>

Thanks for you help. Cheers!

Following code worked for me in D7.
In this example i have specified 2 different layout page for 2 different Node.

page__contact will be converted to page--contact.tpl.php
page__about will be converted to page--about.tpl.php

So create 2 file inside your working named page--contact.tpl.php,page--about.tpl.php for 2 different layout.
*Replace "MYTHEME" with your working theme.
*Do not forget to Clear all caches

<?php
function MYTHEME_preprocess_page(&$variables, $hook) {
  
//Add multiple suggestions for pages based on Node
  
if(arg(1) == 3) {  //For node 3
   
$variables['theme_hook_suggestions'][] =  'page__contact';
   } if(
arg(1) == 4) {   //For node 4
   
$variables['theme_hook_suggestions'][] =  'page__about';
   }
}
?>

Great, this really works.

I used your solution to achieve different page template for specific content type:

<?php
function theme_preprocess_page(&$vars) {
if (
$vars['node']->type == 'contact'){
   
$vars['theme_hook_suggestions'][] = 'page__contact';
}
}
?>

It's a shame that this feature is not supported by default in Drupal 7.

i copied this code and paste it in template.php fie of bluemasters theme and it did not pass for me i guess this function only for some theme

This work for latest release 7.22

Drupal Theme designer and developer.
http://itApplication.net
http://itweb.in

Thanks for this solution, just one thing, it seems safer for me to do extra check:

<?php
function MYTHEME_preprocess_page(&$variables, $hook) {
    if (
array_key_exists('node', $variables)) {
         if (
$variables['node']->type == 'article'){
           
$variables['theme_hook_suggestions'][] = 'page__article';
            }
    }
}
?>

for views etc, there is no $variables['node']

Cheers!

You are a hero. Was looking for this snippet for hours. Thank you very much!

D7.24. Works like a charm.

EDIT: sorry for the confusion, i used szymon.l's solution, right above my comment..... ^

If you want to theme for "Content" (what is really a node), copy the node.tpl.php to a file name that fits the mask "node--view--[VIEW-NAME].tpl.php. Refresh your cache. You're done!

Here is the code snippet for adding the view templates:

<?php
if (property_exists($variables['node'],'view')) {
   
$view = $variables['node']->view;
   
$variables['theme_hook_suggestions'][] = 'node__view__' . $view->name;
   
$variables['theme_hook_suggestions'][] = 'node__view__' . $view->name . '__' . $view->current_display;
}
?>

The code provided by JamieR ( http://drupal.org/node/1089656#comment-4662688 ) worked like a charm!
I did not need the string replacement neither and this function does exactly what I was looking for!

Thank you mate!

The call to str_replace in the D7 version is not only unnecessary, it is wrong! If there is an underscore in the machine name of content type, it will prevent the file from being found. In Drupal 7, the core will take care of replacing underscores with hyphens when producing the name of the override file.

The correct code for Drupal 7 is:

<?php
function themeName_preprocess_page(&$vars, $hook) {
  if (isset(
$vars['node']->type)) {
   
// If the content type's machine name is "my_machine_name" the file
    // name will be "page--my-machine-name.tpl.php".
   
$vars['theme_hook_suggestions'][] = 'page__' . $vars['node']->type;
  }
}
?>

This is great documentation! I'd note a few things that I found a bit of problems with...

Don't forget to add field to your name convention for most fields.. it's easy to miss.

Also, their isn't any documentation referencing taxonomy terms wonder if we can just rename them based on specific vocabularies?

Cheers

for taxonomy you can use:
taxonomy-term--[vocabulary_machine_name].tpl.php
taxonomy-term--[tid].tpl.php

The following helped answer my question about overriding the node.tpl.php file with long content type names in Drupal 7:

In Drupal 6, some template files could be overridden in a targeted way. For example, the theme could contain a "node-article.tpl.php" file which would be used for nodes of the article type only. In Drupal 7, these need to be renamed to use a double-hyphen. For example, "node--article.tpl.php". A single hyphen is still used to separate words: for example, "user-picture.tpl.php" or "node--long-content-type-name.tpl.php", so the double hyphen always indicates a more targeted override of what comes before the "--". As another example, in Drupal 7 the override of a page.tpl.php for node/17 is page--node--17.tpl.php (in Drupal 6 it would have been page-node-17.tpl.php).

comment--[node-type].tpl.php

-drupal 7.9 installation.

comment.tpl.php works. however I have a content type 'media' that I created comment--node-media.tpl.php it never works. I tried it in many different ways like comment-node-media.tpl.php, comment-node--media.tpl.php, etc. not working.

Please advise me to use comment template.

Thanks in advance.

Did you try "comment--media.tpl.php"? For me, if my content type's machine name is "xyz", then:

1. for the comment wrapper template I have to do: "comment-wrapper--node-xyz.tpl.php".
2. But for the comment template itself I have to do: "comment--xyz.tpl.php". Note the lack of the word "node".

Ive got a bug raised in core that seems to be confirmed at the moment:

http://drupal.org/node/1392494

but I am intrigued as to how yours is working when mine isnt....

Using Drupal 7.10. Actually it's not working. I had been making so many changes to my site's theme functions and templates that I thought I was using a custom comment--xyz.tpl.php when in fact this file was an exact duplicate of the base comment.tpl.php. I just tried editing it now and my changes don't show up (with theme registry rebuilding on). The comment-wrapper override does work however.

Im using Drupal 7.12 and the following worked for me:

comment template per content type:
comment--node-[type].tpl.php
eg. comment--node-article.tpl.php

thanks for that.

comment wrapper per content type is
eg. article content type
comment-wrapper--node-article.tpl.php

A function template behaves like a function except that the template can have arguments of many different types. In other words, a function template represents a family of functions.
visit our website

To extend upon http://drupal.org/node/1089656#comment-5408170:

If you have a module called my_module, the template theming blocks for that module is block--my_module.tpl.php. The underscore in "my_module" does not become a hyphen.

In block names (deltas), however, underscores do become hyphens. The template for theming the "my_block" block in the "my_module" module is block--my_module--my-block.tpl.php.

Hi,

I wan't the exact same URL render differently from a normal and an ajax request. When enabling caching Drupal always loads the first rendered content. Is there a workaround to let Drupal use different caches for different theme suggestions?

according to this comprehensive list of Default Theme Hook Suggestions in Core, I have been trying to theme taxonomy terms by copying /modules/taxonomy/taxonomy-term.tpl.php to my theme's path as taxonomy-term--tags.tpl.php

I modified the new file simply to check that it's being used:

  <div class="content">
    <?php
     
//print render($content);
     
echo " page = ".$page . "  file = " . __FILE__ ;
   
?>

  </div>

to my surprised, I found that "echo" line was printed as expected, but $content has been rendered although commented out...

have cleaned cache and rebuilt registry to make sure, but no matter what I do $content is still rendered. Where is it coming from?

any idea ?? Thanks !!

Have you tried to use this function?

<?php
  hide
($content);
?>

Alex.

If I want all the topics and posts of my forum #7 (http://mysite/forum/7/*) to have their own "look" :
Do I need to create forums--topics--7.tpl.php ?
Will forums--7.tpl.php take care of the main page of forum #7 ?

How do I override for a panels page?
I'm using the code
function ThemeName_preprocess_page(&$vars) {
if($panel_page = page_manager_get_current_page()) {
// add a generic suggestion for all panel pages

$variables['theme_hook_suggestions'][] = 'page__panel';
// add the panel page machine name to the template suggestions
$variables['theme_hook_suggestions'][] = 'page__' . $panel_page['name'];
if($panel_page['name'] == 'node_view') {
$vars['theme_hook_suggestions'][] = 'page__node_view';
}
} in template.php
and I've created a file page--node-view.tpl.php and put it under ThemeName/
but I can't get it to work.
Any ideas why?
Thanks

LTech

page--node_view.tpl.php worked.

LTech

In addition to these examples, if you are using Panelizer to Panelize your node pages to layout your content note that tpl template files are available for panels, if you use the Devel_Themer module (with Devel), turn it on and hover over your panel it will suggest the file you need to create (and also the file whose contents you would need to base it off). I've had success with this.

i would like to change all nodes when they are in a taxonomy page. i read that it existed, but when i tried (clear cache and it is in my subtheme templates folder with other templates that work) it didnt work.
i had to make a node.tpl.php and use

<?php
if(arg(0) != 'taxonomy'){
  
//normal printing
}else{
  
//what i want
}
?>

if anybody has other way, i am welcome to learn :)

//trying to answer one question for each one that i make.
//this way, drupal will be more friendly and strong

how to make "page--content-type-edit"?

Drupal 7 default regions:

regions[header] = Header
regions[highlighted] = Highlighted
regions[help] = Help
regions[content] = Content
regions[sidebar_first] = Left sidebar
regions[sidebar_second] = Right sidebar
regions[footer] = Footer

You can override the values for your specific needs.

www.sterlosoft.com

Sam Sterlin S.

page--node.tpl.php (and prefix is set to page__node) I guess this is the node id. may be a link to an example would help.
page--node--%.tpl.php is the % a variable? what is it?
page--node--1.tpl.php (prefix is not changed because the component is a number) 1 stands for what?
page--node--edit.tpl.php (and prefix is set to page__node__edit) is this reserved for when the page is edited? Is that what edit means.

poor poor poor documentation.
why do you think I do not recommend Drupal.

To avoid frustration on setting up template files.
Be sure that you have flushed the Cache.

Hey,
I am new to D7. So I just want to know is there any way to add custom markup to a particular page and if yes how shall I do it??
I have a page "localhost/drupal/node/xyz/qwe" and I want my custom markup to populate in the qwe page.How shall I do it?

Waiting for response...
Thanks,
Rajat