Check your version

This video 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: 

Adding Additional Settings for Field Formatters

Video loading...

Join Drupalize.Me to watch this video

Join today and gain instant access to our entire video library.

Log in Sign up
  • 0:01
    Adding Additional Settings for Field Formatters with Joe Shindelar.
  • 0:07
    [WATER DROP NOISE]
  • 0:07
    In the previous lesson,
  • 0:09
    we added an RGB box field formatter, which displays a color swatch using
  • 0:13
    the data collected for the field.
  • 0:15
    Wouldn't it be nice if we could allow site administrator's a little
  • 0:18
    more control over the size of that color swatch?
  • 0:21
    In this Lesson
  • 0:21
    JOE SHINDELAR: In this lesson, we'll look
  • 0:23
    at using hook_field_formatter_settings_from

Adding Additional Settings for Field Formatters

Loading...

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;
}
Downloads: 
Log in or sign up to download companion files.