[Summary view] [Print] [Text view]

   1  <!-- $Id: theme-field-templates.html,v 1.1.2.4 2008/12/08 20:00:35 yched Exp $ -->
   2  <p>Field-level theming determines how the values of a given field are
   3  displayed. The resulting output ends up in the <span class="code">$content</span>
   4  and <span class="code">$&lt;FIELD_NAME&gt;_rendered</span> variables in the node
   5  templates.</p>
   6  
   7  <h3>Template files</h3>
   8  
   9  <p>In order to customize field themeing:</p>
  10  
  11  <ul>
  12    <li>
  13      Copy the <span class="code">content-field.tpl.php</span> template file into
  14      your theme's root folder (please keep the contents of the
  15      <span class="code">cck/theme</span> folder untouched. For the same reason,
  16       need to copy the file instead of just moving it).
  17    </li>
  18    <li>
  19      Edit that copy to your liking. See the comments in
  20      <span class="code">cck/theme/content/content-field.tpl.php</span> for a list
  21      of all variables available in this template.
  22    </li>
  23  </ul>
  24  
  25  <h3>Template suggestions</h3>
  26  
  27  <p>In addition, the theme layer will also look for field-specific variants
  28  (suggestions), in the following order of precedence:</p>
  29  
  30  <dl>
  31    <dt>content-field-&lt;FIELD_NAME&gt;-&lt;CONTENT_TYPE_NAME&gt;.tpl.php</dt>
  32    <dd>
  33      ex: <span class="code">content-field-field_myfield-story.tpl.php</span> -
  34      If present, will be used to theme the 'field_myfield' field when displaying
  35      a 'story' node.
  36    </dd>
  37  
  38    <dt>content-field-&lt;CONTENT_TYPE_NAME&gt;.tpl.php</dt>
  39    <dd>
  40      ex: <span class="code">content-field-story.tpl.php</span> - If present,
  41      will be used to theme all fields of 'story' nodes.
  42    </dd>
  43  
  44    <dt>content-field-&lt;FIELD_NAME&gt;.tpl.php</dt>
  45    <dd>
  46      ex: <span class="code">content-field-field_myfield.tpl.php</span> -
  47      If present, will be used to theme all 'field_myfield' field in all the
  48      content types it appears in.
  49    </dd>
  50  
  51    <dt>content-field.tpl.php</dt>
  52    <dd>
  53      If none of the above is present, the base template will be used.
  54    </dd>
  55  </dl>
  56  
  57  <strong>Important:</strong>
  58  <ul>
  59    <li>
  60      Suggestions work only if the theme also has the base template file.
  61      If your theme has <span class="code">content-field-*.tpl.php</span> files,
  62      it must also have a <span class="code">content-field.tpl.php</span> file.
  63    </li>
  64    <li>
  65      Whenever you add new template files in your theme, you need to
  66      rebuild the theme registry, or the theme engine won't see them.<br/>
  67      You can do that by :<br/>
  68      - visiting the <a href="&base_url&admin/build/modules">Administer modules</a> page<br/>
  69      - or using <a href="http://www.drupal.org/project/devel">Devel module</a>'s
  70      'clear cache' link.
  71    </li>
  72  </ul>
  73  
  74  <p>See the <a href="http://drupal.org/node/223440">Working with template suggestions</a>
  75  section of the <a href="http://drupal.org/theme-guide">Theme guide for Drupal 6</a>
  76  for more informations about templates and template suggestions.</p>