function theme_field

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 'article' content type, any of the following functions will override this default implementation. The first of these functions that exists is used:

• THEMENAME_field__body__article()
• THEMENAME_field__article()
• 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 Drupal installation to somewhere within the theme's folder and customize it, just like customizing other Drupal 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 'article' content type, any of the following templates will override this default implementation. The first of these templates that exists is used:

• field--body--article.tpl.php
• field--article.tpl.php
• field--body.tpl.php
• field.tpl.php

So, if the body field on the article content type needs customization, a field--body--article.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.
• title_attributes: A string containing the attributes for the title.
• label: The label for the field.
• content_attributes: A string containing the attributes for the content's div.
• items: An array of field items.
• item_attributes: An array of attributes for each item.
• classes: A string containing the classes for the wrapping div.
• attributes: A string containing the attributes for the wrapping div.

See also

template_preprocess_field()

template_process_field()

field.tpl.php

Related topics

File

drupal/modules/field/field.module, line 1176

Attach custom data fields to Drupal entities.

Code

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

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

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

  // Render the top-level DIV.
  $output = '<div class="' . $variables['classes'] . '"' . $variables['attributes'] . '>' . $output . '</div>';
  return $output;
}