<?php
/**
* @file
* Hooks provided by the Field UI module.
*/
/**
* @addtogroup field_types
* @{
*/
/**
* Add settings to a field settings form.
*
* Invoked from field_ui_field_settings_form() to allow the module defining the
* field to add global settings (i.e. settings that do not depend on the bundle
* or instance) to the field settings form. If the field already has data, only
* include settings that are safe to change.
*
* @todo: Only the field type module knows which settings will affect the
* field's schema, but only the field storage module knows what schema
* changes are permitted once a field already has data. Probably we need an
* easy way for a field type module to ask whether an update to a new schema
* will be allowed without having to build up a fake $prior_field structure
* for hook_field_update_forbid().
*
* @param $field
* The field structure being configured.
* @param $instance
* The instance structure being configured.
* @param $has_data
* TRUE if the field already has data, FALSE if not.
*
* @return
* The form definition for the field settings.
*/
function hook_field_settings_form($field, $instance, $has_data) {
$settings = $field['settings'];
$form['max_length'] = array(
'#type' => 'textfield',
'#title' => t('Maximum length'),
'#default_value' => $settings['max_length'],
'#required' => FALSE,
'#element_validate' => array('element_validate_integer_positive'),
'#description' => t('The maximum length of the field in characters. Leave blank for an unlimited size.'),
);
return $form;
}
/**
* Add settings to an instance field settings form.
*
* Invoked from field_ui_field_edit_form() to allow the module defining the
* field to add settings for a field instance.
*
* @param $field
* The field structure being configured.
* @param $instance
* The instance structure being configured.
*
* @return
* The form definition for the field instance settings.
*/
function hook_field_instance_settings_form($field, $instance) {
$settings = $instance['settings'];
$form['text_processing'] = array(
'#type' => 'radios',
'#title' => t('Text processing'),
'#default_value' => $settings['text_processing'],
'#options' => array(
t('Plain text'),
t('Filtered text (user selects text format)'),
),
);
if ($field['type'] == 'text_with_summary') {
$form['display_summary'] = array(
'#type' => 'select',
'#title' => t('Display summary'),
'#options' => array(
t('No'),
t('Yes'),
),
'#description' => t('Display the summary to allow the user to input a summary value. Hide the summary to automatically fill it with a trimmed portion from the main post.'),
'#default_value' => !empty($settings['display_summary']) ? $settings['display_summary'] : 0,
);
}
return $form;
}
/**
* Add settings to a widget settings form.
*
* Invoked from field_ui_field_edit_form() to allow the module defining the
* widget to add settings for a widget instance.
*
* @param $field
* The field structure being configured.
* @param $instance
* The instance structure being configured.
*
* @return
* The form definition for the widget settings.
*/
function hook_field_widget_settings_form($field, $instance) {
$widget = $instance['widget'];
$settings = $widget['settings'];
if ($widget['type'] == 'text_textfield') {
$form['size'] = array(
'#type' => 'textfield',
'#title' => t('Size of textfield'),
'#default_value' => $settings['size'],
'#element_validate' => array('element_validate_integer_positive'),
'#required' => TRUE,
);
}
else {
$form['rows'] = array(
'#type' => 'textfield',
'#title' => t('Rows'),
'#default_value' => $settings['rows'],
'#element_validate' => array('element_validate_integer_positive'),
'#required' => TRUE,
);
}
return $form;
}
/**
* Specify the form elements for a formatter's settings.
*
* This hook is only invoked if hook_field_formatter_settings_summary()
* returns a non-empty value.
*
* @param $field
* The field structure being configured.
* @param $instance
* The instance structure being configured.
* @param $view_mode
* The view mode being configured.
* @param $form
* The (entire) configuration form array, which will usually have no use here.
* @param $form_state
* The form state of the (entire) configuration form.
*
* @return
* The form elements for the formatter settings.
*/
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;
}
/**
* Return a short summary for the current formatter settings of an instance.
*
* If an empty result is returned, the formatter is assumed to have no
* configurable settings, and no UI will be provided to display a settings
* form.
*
* @param $field
* The field structure.
* @param $instance
* The instance structure.
* @param $view_mode
* The view mode for which a settings summary is requested.
*
* @return
* A string containing a short summary of the formatter settings.
*/
function hook_field_formatter_settings_summary($field, $instance, $view_mode) {
$display = $instance['display'][$view_mode];
$settings = $display['settings'];
$summary = '';
if ($display['type'] == 'text_trimmed' || $display['type'] == 'text_summary_or_trimmed') {
$summary = t('Length: @chars chars', array('@chars' => $settings['trim_length']));
}
return $summary;
}
/**
* @} End of "addtogroup field_types".
*/