Template files

All themes usually come with a default node.tpl.php template, if yours does not you can copy it from the node module found under modules/node in your Drupal installation. Drupal core lets you use the following variant for each content type that you define on your site:

node-<CONTENT_TYPE_NAME>.tpl.php
ex: node-story.tpl.php - If present, will be used to theme a 'story' node.

Important: whenever you add new template files in your theme, you need to rebuild the theme registry, or the theme engine won't see them. You can do that by:

  • visiting the Administer modules page (/admin/build/modules).
  • or using Devel module's 'clear cache' link.

Template variables

CCK makes the following variables available in your theme's node templates:

$<FIELD_NAME>_rendered
Contains the rendered html for the field, including the label and all the field's values, with the settings defined on the Display fields tab.
$<GROUP_NAME>_rendered
Contains the rendered html for the fieldgroup (if any), including the label and all the group's fields, with the settings defined on the Display fields tab.

This variable therefore includes the html contained in all the $<FIELD_NAME>_rendered variables for the group's fields.
$FIELD_NAME
Contains the raw values of the fields, in the usual array-format used internally by CCK. What you find in there depends on the field type.

Each value also contains a 'view' element, that holds the ready-to-display value as rendered by the formatter. For instance:

array(
  0 => array(
  'nid' => 5,
  'view' => '&lt;a href="node/5"&gt;Title of node 5&lt;/a&gt;',
  ),
);

Raw data are not sanitized for output, it is therefore not advised to use them directly. Use the 'view' value, or run the values through content_format().

Excluding fields from the $content variable

By default, the $content variable used in node templates contains the rendered html for the whole node : CCK fields and fieldgroups, but also body, file attachments, fivestar widgets, ...

If for some fields you want to use the more fine-grained variables described above, you might want to use the Exclude checkboxes on the Display fields screen, so that the output of those fields is excluded from the $content variable.

Note that there are 'exclude' checkboxes for both the teaser and the full-node view. If you have limited screen space, you may not see the 'full-node' view's exclude column as it may be scrolled off the right hand side of your screen.

You can then customize the display and layout of some CCK fields or groups using the $<FIELD_NAME>_rendered / $<GROUP_NAME>_rendered variables, and trust $content to display 'the rest' without getting duplicate information.

Advanced trick

The Exclude checkboxes affect all active themes. On sites with multiple themes, however, the list of fields to exclude from $content might need to be different across the themes, depending on how their respective node templates are structured.

A theme can bypass those settings by overriding the theme_content_exclude() function to specify the list of fields to exclude for this theme (see the PHPDoc of the function for more information).

Special case : nodes in nodereference fields

In addition to the above, the following suggestions will be looked for in priority for nodes that are displayed as values of a nodereference field using the 'teaser' or 'full node' formatters:

node-nodereference-<REFERRING_FIELD_NAME>-<TYPE_NAME>.tpl.php
ex: node-nodereference-field_noderef-story.tpl.php - If present, will be used to theme a 'story' node when refererenced in the 'field_noderef' field.
node-nodereference-<TYPE_NAME>.tpl.php
ex: node-nodereference-story.tpl.php - If present, will be used to theme a 'story' node when refererenced in any nodereference field.
node-nodereference-<REFERRING_FIELD_NAME>.tpl.php
ex: node-nodereference-field_noderef.tpl.php - If present, will be used to a node refererenced in the 'field_noderef' field.
node-nodereference.tpl.php
If present, will be used to theme nodes referenced in nodereference fields.

The following additional variables are available in templates for referenced nodes:

$referring_field
The nodereference field that references the current node.
$referring_node
The node referencing the current node.

Comments

webthingee’s picture

From within my template file I was unable to get
dsm($referring_field);
dsm($referring_node);

but I was able to get...
dsm($referencing_field);
dsm($referencing_node);

Did this change, or am I using it incorrect?

lucyconnuk’s picture

It seems that there must also be an original node.tpl.php template present in your theme directory or the template suggestion is ignored. This is referred to on http://drupal.org/node/17565 for D4/D5 but it also seems to be true for D6.

wcndave’s picture

I have a content type called "season"

I am using corolla which has node.tpl.php in the module folder.
I copied it to node-season.tpl.php and made some changes.
I then flushed all caches.

however the changes do not show for nodes of that content type...

what could i be doing wrong?

mhedstrom’s picture

I'm having the same problem as wcndave. I have a content type called "Gallery". Already have a node.tpl.php. Created a node-Gallery.tpl.php, flushed all the caches, and it's still reading the node.tpl.php. This is under Drupal 6.

EDIT: I did a

print_r(get_defined_vars());

at the top of my node.tpl.php, and found out that the type was actually node_gallery_gallery. So, creating a file called node-node_gallery_gallery.tpl.php worked, so you might want to try something similar.