Core templates and suggestions

Last modified: June 4, 2009 - 17:49

These templates and suggestions are also available in a cheat sheet (PDF)

Default templates:

These are the default template (.tpl.php) files provided by core. 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.

The templates handled by PHPTemplate in 5.x were also moved. PHPTemplate no longer handles template files.

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

Aggregator

"modules/aggregator/..."

Block

"modules/system/..."

"modules/block/..."

Book

"modules/book/..."

Comment

"modules/comment/..."

Forum

"modules/forum/..."

Node

"modules/node/..."

Poll

"modules/poll/..."

Profile

"modules/profile/..."

Search

"modules/search/..."

User

"modules/user/..."

System

"modules/system/..."

Template suggestions:

What's a template suggestion? It's an alternate template (tpl) file that you have created to override the base or original tpl 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.

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 in 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 properly setup first.

node-[type].tpl.php

base template: node.tpl.php

Node content type, e.g., "node-story.tpl.php", "node-blog.tpl.php", etc.

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 through "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 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 inside "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 to 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.

Delta value in block template files

nielsbom - August 22, 2008 - 13:01

I checked for the meaning of "delta" in #drupal-support.

A module can be programmed to output zero or more blocks. The delta (with value 0) in block-user-0.tpl.php points to the first block the user module was programmed to output.

More info at the API http://api.drupal.org/api/function/hook_block/6 although I still don't understand exactly how that works.

EDITED: removed reference to using strings in place of numbers arbitrarily.

-Niels

Automatic node-[nid].tpl.php template suggestions

psynaptic - November 18, 2008 - 13:45

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

node-[nid].tpl.php template suggestions didn't work

achilles085 - November 25, 2008 - 03:25

I put the code at my template.php file but still my node-21.tpl.php doesn't work...
what would possibly go wrong with this?

Anywayz, thanx for this tip...any help is much appreciated...

GO DRUPALERS!!!

Maybe you forgot about the

m.indyk - December 1, 2008 - 09:11

Maybe you forgot about the node.tpl in your theme. Suggestions doesnt work without the mama template in the theme direcotry. (In this case node.tpl)

Thanks for that tip about

budda - December 1, 2008 - 23:12

Thanks for that tip about needing a mamma node.tpl.php in order to use the type specific node-[type].tpl.php files! Was driving me bonkers.

page.tpl.php

ceci123 - March 23, 2009 - 13:48

How can I use multiple page.tpl.php(with different name) to create multiple layouts for a single site?

I read somewhere that you can create multiple pages like this, eg. page-layout1.tpl.php, page-layout2.tpl.php, page-contactus.tpl.php...etc.

I created a test page called page-contactus.tpl.php.
When I go to my site and type like this http://example.com/druap/?q=contactus
I can see my new page created with plain HTML but if I add any menus it won't render. Eg. adding this code won't do anything:

<?php if (isset($primary_links)) : ?>
<?php print theme('links', $primary_links, array('class' => 'links primary-links')) ?>
<?php endif; ?>

For clarification this code works just find on the page.tpl.php

Can anyone please help.

thank you all

_C

HELP how to name menu template file ?

Kiev1.org - June 25, 2009 - 09:43

menu-menuname.tpl.php ??? not work!
help!
aggregator-item.tpl.php also not work in theme directory

 
 

Drupal is a registered trademark of Dries Buytaert.