function hook_field_formatter_view

7 field.api.php hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display)

Build a renderable array for a field value.

Parameters

$entity_type: The type of $entity.

$entity: The entity being displayed.

$field: The field structure.

$instance: The field instance.

$langcode: The language associated with $items.

$items: Array of values for this field.

$display: The display settings to use, as found in the 'display' entry of instance definitions. The array notably contains the following keys and values;

  • type: The name of the formatter to use.
  • settings: The array of formatter settings.

Return value

A renderable array for the $items, as an array of child elements keyed by numeric indexes starting from 0.

Related topics

Field Formatter API
Define Field API formatter types.
Hooks
Allow modules to interact with the Drupal core.
7 functions implement hook_field_formatter_view()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

field_test_field_formatter_view in modules/field/tests/field_test.field.inc
Implements hook_field_formatter_view().
file_field_formatter_view in modules/file/file.field.inc
Implements hook_field_formatter_view().
image_field_formatter_view in modules/image/image.field.inc
Implements hook_field_formatter_view().
list_field_formatter_view in modules/field/modules/list/list.module
Implements hook_field_formatter_view().
number_field_formatter_view in modules/field/modules/number/number.module
Implements hook_field_formatter_view().

... See full list

File

modules/field/field.api.php, line 1198

Code

function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = array();
  $settings = $display['settings'];

  switch ($display['type']) {
    case 'sample_field_formatter_simple':
      // Common case: each value is displayed individually in a sub-element
      // keyed by delta. The field.tpl.php template specifies the markup
      // wrapping each value.
      foreach ($items as $delta => $item) {
        $element[$delta] = array('#markup' => $settings['some_setting'] . $item['value']);
      }
      break;

    case 'sample_field_formatter_themeable':
      // More elaborate formatters can defer to a theme function for easier
      // customization.
      foreach ($items as $delta => $item) {
        $element[$delta] = array(
          '#theme' => 'mymodule_theme_sample_field_formatter_themeable',
          '#data' => $item['value'],
          '#some_setting' => $settings['some_setting'],
        );
      }
      break;

    case 'sample_field_formatter_combined':
      // Some formatters might need to display all values within a single piece
      // of markup.
      $rows = array();
      foreach ($items as $delta => $item) {
        $rows[] = array($delta, $item['value']);
      }
      $element[0] = array(
        '#theme' => 'table',
        '#header' => array(t('Delta'), t('Value')),
        '#rows' => $rows,
      );
      break;
  }

  return $element;
}

Comments

Posted by manimejia on

This hook is invoked (and default values for $element are set) by function field_default_view()

Posted by stickywes on

If you are producing a formatter that produces an $element (or whatever your return variable is) array that has more keys than your $item count, you should consider adding these extra elements to $items using
hook_field_prepare_view().

Without doing so, you'll end up with field_view_field() returning render arrays with inconsistent amounts in the "raw" section of the array and the "rendered" section of the array.

For instance, if I got up to $element[10] and only actually have 5 $items, consider this snippet from the Views module.

   $render_array = field_view_field($entity_type, $entity, $this->definition['field_name'], $display,   $langcode);

    foreach (element_children($render_array) as $count) {
      $items[$count]['rendered'] = $render_array[$count];
      $items[$count]['raw'] = $render_array['#items'][$count];
    }

The second line in the foreach will generate warnings. Other modules will assume your rendered content is based on your $items.

Posted by stickywes on

I should also add that if you're doing a lot of work on the data in THIS hook you should probably consider moving that work to the prepare hook, as well.

I also meant hook_field_formatter_prepare_view(), woops!

Posted by martin_q on

If you have a field that outputs something but has an empty input widget and/or stores nothing in the database, $items will be an empty array, and as a result the formatter will not be rendered even though you return a render array from your implementation of this hook. As stickywes points out, you need to ensure that $items contains as many values as your returned array. There's a good example of a dummy hook_field_prepare_view function here: http://api.drupal.org/comment/48043#comment-48043

Posted by joelpittet on

Just an FYI, if you decide you need to change a core field_formatter_view, and define this hook in your module... remember to define the hook_field_formatter_info with the same details in your module. The formatter info doesn't carry through/cascade to your module from the original.

/**
* Implements hook_field_formatter_info().
*/
function mymodule_field_formatter_info() {
  return array(
    'taxonomy_term_reference_plain' => array(
      'label' => t('Plain text'),
      'field types' => array('taxonomy_term_reference'),
    ),
  );
}

/**
* Implements hook_field_formatter_view().
*/
function mymodule_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = array();
  switch ($display['type']) {
    // Override check plain
    case 'taxonomy_term_reference_plain':
      foreach ($items as $delta => $item) {
        $name = ($item['tid'] != 'autocreate' ? $item['taxonomy_term']->name : $item['name']);
        $element[$delta] = array(
          '#markup' => mymodule_crazy_fun_plain($name),
        );
      }
    break;
  }
  return $element;
}

Posted by sarav.din33 on

I implement this hook in my module.
But it won't affect at all.
My Code like this:

/**
* Implements hook_field_formatter_view().
*/
function mymodule_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  //My Snippet
}

But another hook get worked:

/**
* Implements hook_field_formatter_info().
*/
function mymodule_field_formatter_info() {
  //My Snippet
}

Is there any issue in this case.