[Summary view] [Print] [Text view]

   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>