Last updated March 4, 2013. Created by LeeHunter on November 9, 2007.
Edited by lundj, thomaske, silverwing, siliconmeadow. Log in to edit this page.

Default templates:

These are the default template (.tpl.php) files provided by core in Drupal 7. Documentation on the variables and purpose of these templates are located inside the templates. There is a default set of variables available to all templates.

Drupalize.Me offers a free, eight-minute video on the ins and outs of modifying template.php...

Overview of Template.PHP

In order to override these templates, all you need to do is copy them into your theme folder and clear the theme registry.

To override templates in a more targeted way, see Drupal 7 Template Suggestions or Drupal 6 Template Suggestions.

Aggregator
"modules/aggregator/..."
Block
"modules/block/..."

Note: the Drupal 6 version of block.tpl.php used to be part of "modules/system/...".

Book
"modules/book/..."
Comment
"modules/comment/..."

Note: comment-folded.tpl.php has been deprecated in Drupal 7.

Field
"modules/field/theme/..."

Note: field.tpl.php is a new template in Drupal 7.

Forum
"modules/forum/..."

Note: forum-topic-navigation.tpl.php has been deprecated in Drupal 7.

Node
"modules/node/..."
Overlay
"modules/overlay/..."

Note: overlay.tpl.php is a new template in Drupal 7.

Poll
"modules/poll/..."

Note: Former templates poll-results-block.tpl.php and poll-bar-block.tpl.php have been renamed with a double dash in Drupal 7.

Profile
"modules/profile/..."
Search
"modules/search/..."

Note: search-theme-form.tpl.php has been deprecated in Drupal 7.

System
"modules/system/..."

Note: box.tpl.php has been deprecated in Drupal 7. html.tpl.php and region.tpl.php have been added.

Taxonomy
"modules/taxonomy/..."

Note: taxonomy-term.tpl.php is a new template in Drupal 7.

Toolbar
"modules/toolbar/..."

Note: toolbar.tpl.php is a new template in Drupal 7.

User
"modules/user/..."

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

Comments

Using <?php $vars['template_file'] ?> it is possible to create your own template file suggestions. Here is an example to allow use of node-[nid].tpl.php files.

<?php
/**
* Override or insert variables into the node templates.
*
* @param $vars
*   An array of variables to pass to the theme template.
* @param $hook
*   The name of the template being rendered ("node" in this case.)
*/
function phptemplate_preprocess_node(&$vars, $hook) {
 
$node = $vars['node'];
 
$vars['template_file'] = 'node-'. $node->nid;
}
?>

Drupal Contributions API

In case you don't scroll down to the comments below and read through the code posted, note that there's a $vars['template_files'] array -- use this to ADD to the possible template suggestions, rather than specify a single one directly.

In my case, I wanted several node types to use one template. My code (in my theme's preprocess_node function) is along the lines of:

<?php
if(substr($vars['node']->type, 0, 5) == 'media') {
   
$vars['template_files'][] = 'node-media';
}
?>

Realy helpful for me!

One thing that I had to find out by trial and error:

A node's teaser view is generated by node.tpl.php. If you want to show or hide node contents for teaser views, you would check to see if the $teaser variable is true.

An example: Say you wanted to have taxonomy terms visible in a node's full view, but not in the teaser. In node.tpl.php, you would change this:

<?php if ($terms): ?>
  <div class="terms terms-inline"><?php echo $terms ?></div>
<?php endif;?>

...to this:

<?php if ($terms && !$teaser): ?>
  <div class="terms terms-inline"><?php echo $terms ?></div>
<?php endif;?>

Note the && !$teaser part of the PHP if statement.

It appears that the $teaser variable is only available to node.tpl.php, but I could be wrong about this.

-Karlheinz

Edit /sites/all/themes/YOURTHEME/template.php to include:

<?php
function phptemplate_preprocess_node(&$vars) {
 
//default template suggestions for all nodes
 
$vars['template_files'] = array();
 
$vars['template_files'][] = 'node';
  if (
drupal_is_front_page()) {
   
$vars['template_files'][] = 'node-front';
  }
 
//individual node being displayed
 
if($vars['page']) {
   
$vars['template_files'][] = 'node-page';
   
$vars['template_files'][] = 'node-'.$vars['node']->type.'-page';
   
$vars['template_files'][] = 'node-'.$vars['node']->nid.'-page';
  }
 
//multiple nodes being displayed on one page in either teaser
  //or full view
 
else {
   
//template suggestions for nodes in general
   
$vars['template_files'][] = 'node-'.$vars['node']->type;
   
$vars['template_files'][] = 'node-'.$vars['node']->nid;
   
//template suggestions for nodes in teaser view
    //more granular control
   
if($vars['teaser']) {
     
$vars['template_files'][] = 'node-'.$vars['node']->type.'-teaser';
     
$vars['template_files'][] = 'node-'.$vars['node']->nid.'-teaser';
    }
  }
 
//echo "<pre>" . print_r($vars['template_files'], TRUE) . "</pre>"; //TESTING
}
?>

Then copy /modules/node/node.tpl.php to /sites/all/themes/YOURTHEME/node-front.tpl.php and customize it to your needs.

see also Extending Drupal Templating

EDIT: Sorry, I thought you were trying to override PAGE-front.tpl.php, not NODE-front.tpl.php! I'm editing this post accordingly.

Rather than calling this function phptemplate_preprocess_node, you should always call it YOURTHEME_preprocess_node. From Setting up variables for use in a template:

The theme name should always be used for themes. This minimizes any chance of a sub-theme redeclaring a function with a engineName_preprocess prefix and causing fatal PHP errors due to duplicate functions.

Also, setting up a separate node-front.tpl.php template may not be necessary.

All template files are passed a baseline variable called $is_front, a boolean that returns true if the user is viewing the front page. See the Default baseline variables handbook page. If you have anything you want to show or hide, just write a check to see if that variable is true, and put it into the default node.tpl.php template.

For example: Say you want the author's picture to appear on the front page, but nowhere else. Here's the default code from node.tpl.php:

<?php print $picture ?>

In your template's node.tpl.php file, change it to this:

<?php if ($is_front) print $picture; ?>

Hope this helps!

-Karlheinz

This will add all sorts of suggestions. The suggestions derived from the current path will override the suggestions based upon the node type:

<?php
MYTEMPLATE_preprocess_node
(&$vars) {
/**
* NODE TEMPLATE SUGGESTIONS
* Create node.tpl.php suggestions based upon $path & $node
* Templates precedence is FILO.
* So, node-$path templates override node-$node templates. If you want node-$node
* templates to override $path, just swap these to conditional statements.
*/
// Feed everything into a temp array first, 'cause Drush complains.
$suggestions = array();
// Suggest by Node Type
if (isset($vars['node'])) {
// If the node type is "blog" the template suggestion will be "node-blog.tpl.php".
 
$sug = 'node-'. str_replace('_', '-', $vars['node']->type);
 
$suggestions[] = $sug;
}
// Suggest by Path
// if the uri alias is /videos/crazy
// add suggestions of page-videos.tpl.php and page-videos-crazy.tpl.php
if (module_exists('path')) {
 
$alias = drupal_get_path_alias(str_replace('/edit','',$_GET['q']));
  if (
$alias != $_GET['q']) {
   
$template_filename = 'node';
    foreach (
explode('/', $alias) as $path_part) {
     
$template_filename = $template_filename . '-' . $path_part;
     
$suggestions[] = $template_filename;
    }
  }
}
/**
*
* Finally, before sending to node-[x].tpl, make sure there
* aren't any duplicate suggestions.
*/
$suggestions = array_unique($suggestions);
/**
* Now add those suggestions to your template_files array
*/
foreach ($suggestions as $tmp) {
 
$vars['template_files'][] = $tmp;
}
}
// end preprocess_node function
?>

References:
http://adaptivethemes.com/page-template-suggestions-per-node-type
http://drupal.org/node/223440

Joe
http://www.hydeinteractive.com/

Since there is no 'page' module in drupal, where does page.tpl.php come from? How does the application know what to do with this? I can't seem to find any documentation on the origin of this anywhere.

The original default file can be found at /modules/system/page.tpl.php and I guess that it's the PHPTemplate theme engine that does the work with these files. The original project is at http://drupal.org/project/phptemplate .

Scott Jackson
Wollongong NSW Australia

The page template is in the "modules/system/..." folder. That folder has the templates that are absolutely necessary for Drupal to function, without any core modules enabled. These are on the list above, but here's a list of system templates:

-Karlheinz

Is there a way to style the page-node for specific content types in Drupal 7? I've got a custom template page for all page-nodes but I only want it show for a specific content type.

Even thought this page is marked as documentation for both D6 and D7... the tpl.php naming convension for path-specific templates isn't the same between the two... I'm building a D7 site right now and having a LOT of headaches because apparently this changed in D7... you now need TWO '-'s ('page--path.tpl.php') instead of just one. Why this is, I have no idea. It also doesn't seem to be working for region templates. I'm wondering if it's just a bug in the core. See here:

http://drupal.org/node/1071214

I read somewhere that the two dashes add a performance improvement. Not a bug.

From Pro Drupal Development, 3rd Edition, by Todd Tomlinson:

You can also create custom .tpl files for specific pages of your site; for example, you could copy page.tpl.php and create a page--front.tpl.php file. This new template would be applied only to the front page of your site. You can also do the same thing with node.tpl.php. Let’s say you want to theme articles differently than other node types, like a basic page. You can copy node.tpl.php from the modules/node directory to your theme directory and rename that file to node--article.tpl.php. This new template file will override the standard node.tpl.php file for any node that is an article. For additional details, visit the theming guide on Drupal.org at http://drupal.org/documentation/theme.

Yeah.. thanks... I finally found this buried somewhere in the documentation... ugh... oh well.. drive on...

Hi RavenHursT,

Can you share where you found the documentation you're referring too. I just did a lot of my own testing (with results here: http://robmalon.com/drupal-7-0-preprocess-page-templates-theme_hook_sugg...) to try and compile the default page suggestions for Drupal 7. I also created a bit of custom preprocess_page logic to reinvent some of the template suggestions people had access to with similar Drupal 6 solutions.

EG, my page suggestions now look something like this between core and custom suggestions:

[theme_hook_suggestions] => Array
    (
        [0] => page__node
        [1] => page__node__%
        [2] => page__article
        [3] => page__path_1
        [4] => page__path_1__path-2
        [5] => page__path_1__path_2__my-article
        [6] => page__my_article
        [7] => page__node__5
    )

Here ya go Rob, third paragraph in italics:

http://drupal.org/node/190815

Please note that this page documents D6. There are now pages at Core Templates and Drupal 7 Template Suggestions for Drupal 7.

Scott Jackson
Wollongong NSW Australia

The template suggestions have been removed, and there are now template suggestions pages for Drupal 6 and Drupal 7.

However, please note the core templates here are for Drupal 7, with special notes for templates who were added, renamed or deprecated, compared to Drupal 6. The page have been updated following the release of Drupal 7, please see the previous discussion in the Documentation issue queue, and contribute by editing the page if you see mistakes.

I have been banging my head for quite a while trying to figure out why the template for my custom content type wasn't being read - it was indeed the double dash problem.

how can I use taxonomy-term.tpl.php?
I have tried by creating taxonomy-term.tpl.php inside theme folder but it does not override any categoru path.
Please help me with this!

co-founder and technical head, webmaffia

isagarjadhav,
A working example is the original. Start with that, and then customise from there. Either copy it from modules/taxonomy/taxonomy-term.tpl.php or look it up at api.drupal.org

http://api.drupal.org/api/drupal/modules--taxonomy--taxonomy-term.tpl.ph...

Scott Jackson
Wollongong NSW Australia

A little tip that helped me, try filling out a terms description and then see if the tpl file you're expecting gets picked up.

The most productive way to discuss this page is to post an issue about it here:
http://drupal.org/project/issues/documentation
This way, this topic can be properly discussed, prioritized and fixed by anyone who wishes to join the Docs Team.