Sometimes display formatters need to allow for administrators to configure additional settings. For example choosing which image style to use when displaying an image field. The Field API allows for formatter settings and we can add them by implementing hook_field_formatter_settings_summary() and hook_field_formatter_settings_form(). This lesson shows how to add simple width and height settings for the rgb_box display formatter that will allow an admin to modify the dimensions of the block that is displayed. Then uses those entered values in the implementation of hook_field_formatter_view() added in the previous lesson to set the CSS width and height of the HTML element being displayed. Allowing site administrators a greater amount of control over what the content looks like without having to write any code. Which, also makes are module more flexible, and more useful in a larger variety of scenarios.

Field formatter settings are access via the Manage Display tab for our Article content type. Any field which provides additional settings will display a gear icon along on the far right that once clicked will reveal the settings form. Field formatter settings are per instance settings.

In addition to providing a settings form we also need to provide a simple text sumary of the settings that can be displayed on the Manage Display tab. This summary is displayed next to our field prior to someone clicking the gear icon that reveals the settings form. This gives the administrator a quick overview of the current configuration for all fields formatters. This is done with hook_field_formatter_settings_summary(), which despite not being documented as such is required in order to provide field display formatter settings in Drupal 7.

Example:

/**
 * Implements hook_field_formatter_settings_summary().
 */
function rgb_field_formatter_settings_summary($field, $instance, $view_mode) {
  $display = $instance['display'][$view_mode];
  $settings = $instance['display'][$view_mode]['settings'];

  if ($display['type'] == 'rgb_box') {
    $output = t('Box size: @[email protected]', array('@width' => $settings['width'], '@height' => $settings['height']));
    return $output;
  }
}

/**
 * Implements hook_field_formatter_settings_form().
 */
function rgb_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) {
  $display = $instance['display'][$view_mode];
  $settings = $display['settings'];

  $element = array();
  if ($display['type'] == 'rgb_box') {
      $element['width'] = array(
        '#type' => 'textfield',
        '#title' => t('Box width'),
        '#default_value' => $settings['width'],
      );
      $element['height'] = array(
        '#type' => 'textfield',
        '#title' => t('Box height'),
        '#default_value' => $settings['height'],
      );
  }
  
  return $element;
}