| 7 field.api.php | hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) |
| 8 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
7 functions implement hook_field_formatter_view()
File
- modules/
field/ field.api.php, line 1156
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
Invoked by field_default_view()
This hook is invoked (and default values for $element are set) by function field_default_view()
Rendering More Elements Than Items
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.
I should also add that if
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!
Thanks man! You saved me a
Thanks man! You saved me a lot of headache.
View mode
Is there a way to get the view_mode of the entity being viewed?
I've created a formatter that has a setting for the label of a link. I need to translate it using i18n_string so I need to build a unique name. The best choice is to use "textgroup:entity_type:bundle:view_mode:field_name". This name works well in the summary hook but in this one I cant'get the view_mode to form the name.
Thanks!
i have the same problem
i have the same problem.
Yes even I want to know how
Yes even I want to know how to detect the view mode when I am inside hook_field_formatter_view
Ok I figured it out
Ok I figured it out myself.
The thing is when I was building the hook_field_formatter_view() to create gallery of images, I was setting image cache for default as well as teaser view.
When I first took the image cache preset, I took it from $instance available in the hook. But then I realised that it should be taken from $display where you will get the preset for the current display.
// $data['image_style'] = $instance['display']['default']['settings']['pic_size'];
$data['image_style'] = $display['settings']['pic_size'];
Extending an existing field formatter view
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;
}
Looking for node object (or
Looking for node object (or other entity object) ? try the $entity