1.20.x field.theme.inc theme_field($variables)

Returns HTML for a field.

This is the default theme implementation to display the value of a field. Theme developers who are comfortable with overriding theme functions may do so in order to customize this markup. This function can be overridden with varying levels of specificity. For example, for a field named 'body' displayed on the 'post' content type, any of the following functions will override this default implementation. The first of these functions that exists is used:

  • THEMENAME_field__body__post()
  • THEMENAME_field__post()
  • THEMENAME_field__body()
  • THEMENAME_field()

Theme developers who prefer to customize templates instead of overriding functions may copy the "field.tpl.php" from the "modules/field/theme" folder of the Backdrop installation to somewhere within the theme's folder and customize it, just like customizing other Backdrop templates such as page.tpl.php or node.tpl.php. However, it takes longer for the server to process templates than to call a function, so for websites with many fields displayed on a page, this can result in a noticeable slowdown of the website. For these websites, developers are discouraged from placing a field.tpl.php file into the theme's folder, but may customize templates for specific fields. For example, for a field named 'body' displayed on the 'post' content type, any of the following templates will override this default implementation. The first of these templates that exists is used:

  • field--body--post.tpl.php
  • field--post.tpl.php
  • field--body.tpl.php
  • field.tpl.php

So, if the body field on the post content type needs customization, a field--body--post.tpl.php file can be added within the theme's folder. Because it's a template, it will result in slightly more time needed to display that field, but it will not impact other fields, and therefore, is unlikely to cause a noticeable change in website performance. A very rough guideline is that if a page is being displayed with more than 100 fields and they are all themed with a template instead of a function, it can add up to 5% to the time it takes to display that page. This is a guideline only and the exact performance impact depends on the server configuration and the details of the website.

Parameters

$variables: An associative array containing:

  • label_hidden: A boolean indicating to show or hide the field label.
  • label: The label for the field.
  • content_attributes: An array of additional HTML attributes for the content's wrapper div.
  • items: An array of field items.
  • item_attributes: An array of additional HTML attributes for each item.
  • classes: Array containing the classes for the wrapping div.

See also

template_preprocess_field()

field.tpl.php

Related topics

Default theme implementations Functions and templates for the user interface to be implemented by themes.

File

modules/field/field.theme.inc, line 64
Theme functions for the Field module.

Code

function theme_field($variables) {
  $output = '';

  // Render the label, if it's not hidden.
  if (!$variables['label_hidden']) {
    $output .= '<div class="field-label">' . $variables['label'] . ':&nbsp;</div>';
  }

  // Render the items.
  $content_attributes = (isset($variables['content_attributes'])) ? backdrop_attributes($variables['content_attributes']) : '';
  $output .= '<div class="field-items"' . $content_attributes . '>';
  foreach ($variables['items'] as $delta => $item) {
    $classes = 'field-item ' . ($delta % 2 ? 'odd' : 'even');
    $item_attributes = (isset($variables['item_attributes'][$delta])) ? backdrop_attributes($variables['item_attributes'][$delta]) : '';
    $output .= '<div class="' . $classes . '"' . $item_attributes . '>' . backdrop_render($item) . '</div>';
  }
  $output .= '</div>';

  // Render the top-level DIV.
  $output = '<div class="' . implode(' ', $variables['classes']) . '"' . backdrop_attributes($variables['attributes']) . '>' . $output . '</div>';

  return $output;
}