cck/help/theme-node-templates.html

   1 <!-- $Id: theme-node-templates.html,v 1.1.2.5 2008/12/08 20:15:00 yched Exp $ -->
   2 <h3>Template files</h3>
   3
   4 <p>All themes usually come with a default <span class="code">node.tpl.php</span>
   5 template. Drupal core lets you use the following variant (suggestion):</p>
   6
   7 <dl>
   8   <dt>node-&lt;CONTENT_TYPE_NAME&gt;.tpl.php</dt>
   9   <dd>
  10     ex: <span class="code">node-story.tpl.php</span> - If present, will be used
  11     to theme a 'story' node.
  12   </dd>
  13 </dl>
  14
  15 <p><strong>Important:</strong> whenever you add new template files in your theme, you
  16 need to rebuild the theme registry, or the theme engine won't see them.<br/>
  17 You can do that by :<br/>
  18 - visiting the <a href="&base_url&admin/build/modules">Administer modules</a> page<br/>
  19 - or using <a href="http://www.drupal.org/project/devel">Devel module</a>'s
  20 'clear cache' link.</p>
  21
  22 <h3>Template variables</h3>
  23
  24 <p>CCK makes the following variables available in your theme's node templates:</p>
  25
  26 <dl>
  27   <dt>$&lt;FIELD_NAME&gt;_rendered</dt>
  28   <dd>
  29     Contains the rendered html for the field, including the label and all the
  30     field's values, with the settings defined on the <strong>Display fields</strong> tab.
  31   </dd>
  32
  33   <dt>$&lt;GROUP_NAME&gt;_rendered</dt>
  34   <dd>
  35     Contains the rendered html for the fieldgroup (if any), including the label
  36     and all the group's fields, with the settings defined on the <strong>Display
  37     fields</strong> tab.<br/>
  38     This variable therefore includes the html contained in all the
  39     <span class="code">$&lt;FIELD_NAME&gt;_rendered</span> variables for the
  40     group's fields.
  41   </dd>
  42
  43   <dt>$FIELD_NAME</dt>
  44   <dd>
  45     Contains the raw values of the fields, in the usual array-format used
  46     internally by CCK. What you find in there depends on the field type.<br/>
  47     Each value also contains a <span class="code">'view'</span> element, that
  48     holds the ready-to-display value as rendered by the formatter. For instance:
  49     <pre>
  50 array(
  51   0 => array(
  52     'nid' => 5,
  53     'view' => '&lt;a href="node/5"&gt;Title of node 5&lt;/a&gt;',
  54   ),
  55 );</pre>
  56     <strong>Raw data are not sanitized for output, it is therefore not
  57     advised to use them directly</strong>. Use the <span class="code">'view'</span>
  58     value, or run the values through <span class="code">content_format()</span>.
  59   </dd>
  60 </dl>
  61
  62 <h3>Excluding fields from the $content variable</h3>
  63
  64 <p>By default, the <span class="code">$content</span> variable used in node
  65 templates contains the rendered html for the whole node : CCK fields and
  66 fieldgroups, but also body, file attachments, fivestar widgets, ...</p>
  67
  68 <p>If for some fields you want to use the more fine-grained variables described
  69 above, you might want to use the <strong>Exclude</strong> checkboxes on the <strong>Display
  70 fields</strong> screen, so that the output of those fields is excluded from the
  71 <span class="code">$content</span> variable.</p>
  72
  73 <p>You can then customize the display and layout of some CCK fields or groups
  74 using the <span class="code">$&lt;FIELD_NAME&gt;_rendered</span> /
  75 <span class="code">$&lt;GROUP_NAME&gt;_rendered</span> variables, and trust
  76 <span class="code">$content</span> to display 'the rest' without getting
  77 duplicate information.</p>
  78
  79 <h5>Advanced trick</h5>
  80 <p>The <strong>Exclude</strong> checkboxes affect all active themes. On sites with multiple
  81 themes, however, the list of fields to exclude from <span class="code">$content</span>
  82 might need to be different across the themes, depending on how their respective
  83 node templates are structured.</p>
  84
  85 <p>A theme can bypass those settings by overriding the <span class="code">theme_content_exclude()</span>
  86 function to specify the list of fields to exclude for this theme (see the
  87 PHPDoc of the function for more information).</p>
  88
  89
  90 <h3>Special case : nodes in nodereference fields</h3>
  91
  92 <p>In addition to the above, the following suggestions will be looked for
  93 in priority for nodes that are displayed as values of a nodereference field using
  94 the 'teaser' or 'full node' formatters:</p>
  95
  96 <dl>
  97   <dt>node-nodereference-&lt;REFERRING_FIELD_NAME&gt;-&lt;TYPE_NAME&gt;.tpl.php</dt>
  98   <dd>
  99     ex: <span class="code">node-nodereference-field_noderef-story.tpl.php</span> -
 100     If present, will be used to theme a 'story' node when refererenced in the
 101     'field_noderef' field.
 102   </dd>
 103
 104   <dt>node-nodereference-&lt;TYPE_NAME&gt;.tpl.php</dt>
 105   <dd>
 106     ex: <span class="code">node-nodereference-story.tpl.php</span> - If present,
 107     will be used to theme a 'story' node when refererenced in any nodereference
 108     field.
 109   </dd>
 110
 111   <dt>node-nodereference-&lt;REFERRING_FIELD_NAME&gt;.tpl.php</dt>
 112   <dd>
 113     ex: <span class="code">node-nodereference-field_noderef.tpl.php</span> - If
 114     present, will be used to a node refererenced in the 'field_noderef' field.
 115   </dd>
 116
 117   <dt>node-nodereference.tpl.php</dt>
 118   <dd>
 119     If present, will be used to theme nodes referenced in nodereference fields.
 120   </dd>
 121 </dl>
 122
 123 <p>The following additional variables are available in templates for referenced nodes:</p>
 124
 125 <dl>
 126   <dt>$referring_field</dt>
 127   <dd>The nodereference field that references the current node.</dd>
 128
 129   <dt>$referring_node</dt>
 130   <dd>The node referencing the current node.</dd>
 131 </dl>