Module Development

Creating a Field Formatter and Displaying Field Data for Drupal 7

Check your version

This tutorial covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Alternate resources

Fields and the Field API

Displaying that data that was collected and saved for our a field requires creating a field formatter. Formatters consist of an implementation of hook_field_formatter_info() and hook_field_formatter_view(). The former provides meta-data about the formatter for the Field API and the latter does the heavy lifting of determining what the output is actually going to look like.

A module can define more than one field formatter.

Implementations of hook_field_formatter_view() return a renderable array representing the content you would like to display to the end user. Generally this is an escaped version of content provided by a site administrator with some additional HTML formatting applied.

Depending on the values being output you would likely want to also use a theme function for your field formatter by implementing hook_theme() and providing either a theme() function that can be overriden or a template file. We're not going to cover that in this lesson since the focus here is on the technical requirements for impelementing a field formatter. Howerver, I would say that it's best practcie to always output any HTML with a theme function. You can find out more about creating themeable output by watching these videos from our library: http://drupalize.me/videos/integrating-theme-system and http://drupalize.me/videos/using-drupal-render-api

Example:


/**
 * Implements hook_field_formatter_info().
 */
function rgb_field_formatter_info() {
  return array(
    'rgb_raw' => array(
      'label' => t('Raw color value'),
      'field types' => array('rgb_color'),
    ),
    'rgb_box' => array(
      'label' => t('Color block with label'),
      'field types' => array('rgb_color'),
    ),
  );
}

/**
 * Implements hook_field_formatter_view().
 */
function rgb_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, &$items, $display) {
  $element = array();

  switch ($display['type']) {
    case 'rgb_raw':
      foreach ($items as $key => $value) {
        $element[$key] = array(
          '#type' => 'markup',
          '#markup' => t('#@hex', array('@hex' => $value['rgb'])),
        );
      }
      break;

    case 'rgb_box':
      foreach ($items as $key => $value) {
        $element[$key] = array(
          '#type' => 'markup',
          '#markup' => '
' . check_plain($value['label']) . '
',
        );
      }
      break;
  }

 return $element;
}