Module Development

Creating a Field Formatter and Displaying Field Data for Drupal 7

This page is archived

We're keeping this page up as a courtesy to folks who may need to refer to old instructions. We don't plan to update this page.

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;
}

Additional resources