| 7 field_ui.api.php | hook_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) |
| 8 field_ui.api.php | hook_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) |
Specify the form elements for a formatter's settings.
Parameters
$field: The field structure being configured.
$instance: The instance structure being configured.
$view_mode: The view mode being configured.
$form: The (entire) configuration form array, which will usually have no use here.
$form_state: The form state of the (entire) configuration form.
Return value
The form elements for the formatter settings.
Related topics
4 functions implement hook_field_formatter_settings_form()
File
- modules/
field_ui/ field_ui.api.php, line 151 - Hooks provided by the Field UI module.
Code
function hook_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) {
$display = $instance['display'][$view_mode];
$settings = $display['settings'];
$element = array();
if ($display['type'] == 'text_trimmed' || $display['type'] == 'text_summary_or_trimmed') {
$element['trim_length'] = array(
'#title' => t('Length'),
'#type' => 'textfield',
'#size' => 20,
'#default_value' => $settings['trim_length'],
'#element_validate' => array('element_validate_integer_positive'),
'#required' => TRUE,
);
}
return $element;
}
Comments
More of a module callback than a hook
This is not a true hook in the sense that it will ever be generically invoked allowing any module to build the display formatter's settings form. It actually functions more like a module callback that is directly invoked by field_ui_display_overview_form() in field_ui.admin.inc.
That function loops over every field on an entity and looks for a settings form callback from the module defining the field's display formatter to determine if it should be called to add to the display overview form. This means your implementation of this hook need not wonder if it is going to be called for some unrelated display formatter except by intentional developer effort via hook_field_formatter_info_alter().
Need hook_field_formatter_settings_summary too
It appears this is only invoked if a corresponding hook_field_formatter_settings_summary() returns a summary.
Fieldset in your form? set #tree to TRUE
If you define a fieldset in the form you are creating here, you have to set the '#tree' option to true. If you don't do so, your settings will not be saved.
This then of course also means that you have:
- to define your default settings, in hook_field_formatter_info(), tree-wise.
- to use the settings, e.g. in hook_field_formatter_view() and hook_field_formatter_settings_summary(), tree-wise.