scrap pad

Drupal Field Formatters

I develop with Drupal 6 at work. One of the things I've been finding useful recently is writing field formatters. Field formatters are handy because they're used to format CCK field content when it gets displayed in nodes and also to format fields in Views. You can choose between formatters for each field of a node type under the 'Display' tab in the node type's settings. In Views, if you choose a display type that uses fields, you can select a different field formatter when you add each field.

To write your own field formatters, you implement hook_field_formatter_info(), then create theme functions for your formatters and add them to your hook_theme() implementation. At one point this was documented in examples packaged with CCK, but it seems the examples are no longer part of the CCK download.

A simple hook_field_formatter_info() implementation looks like this:

/**
* Implementation of hook_field_formatter_info().
*/
function example_field_formatter_info() {
  return array(
    'myformatter' => array(
      'label' => t('My Formatter'),
      'field types' => array('text'),
      'multiple values' => CONTENT_HANDLE_CORE,
    ),
  );
}

• Your formatter should have a unique handle, in this case "myformatter". Using "x_formatter" or "x_module_name" here makes the theme key name confusing.
• The 'field types' array contains the names of cck field types applicable to this formatter.
• 'multiple values' determines the way field content is passed to the theme function. It may be either of two values:
  • CONTENT_HANDLE_CORE means that the formatter is called separately for each value in the field. If a field contains multiple values, then the formatter is called multiple times. Field content is passed to the formatter in $element['#item']. This is the default.
  • CONTENT_HANDLE_MODULE means that the formatter is called only once for a field, and the theme formatter gets all the field values at once. In this case, field content is passed to the formatter in $element[0]['#item'], $element[1]['#item'], $element[2]['#item'], etc. Note that the $elements array contains other information about the field, such as $element['#field_name']

You will need to add the field formatter theme function to your hook_theme() implementation:

/**
* Implementation of hook_theme().
*/
function exmaple_theme($existing, $type, $theme, $path) {
  return array(
    'example_formatter_myformatter' => array(
      'function' => 'theme_myformatter',
      'arguments' => array('element' => NULL),
    ),
  );
}

• The theme array key, in this case 'example_formatter_myformatter' is constructed from {module name}_formatter_{formatter name}.
• You don't need to include the 'function' => 'theme_myformatter' line; the default theme function name in this case would be 'theme_example_formatter_myformatter'.

The formatter function itself should return a stuff that is ready to output to the browser:

/**
* Theme function for myformatter from hook_field_formatter_info().
* @param $element
*   Array of formatter info and the item to theme. Field contents will either be
*   in $element['#item'] or $element[$i]['#item'].
*/
function theme_example_formatter_myformatter($element) {
  return strtoupper($element['#item']['safe']);
}

This field formatter simply displays the contents of the text field in all caps. You'll need to clear your cache before your new formatter shows up in the field display choices.