field_ui.api.php

Hooks provided by the Field UI module.

File

drupal/modules/field_ui/field_ui.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Field UI module.
  5. */
  6. /**
  7. * @addtogroup field_types
  8. * @{
  9. */
  10. /**
  11. * Add settings to a field settings form.
  12. *
  13. * Invoked from field_ui_field_settings_form() to allow the module defining the
  14. * field to add global settings (i.e. settings that do not depend on the bundle
  15. * or instance) to the field settings form. If the field already has data, only
  16. * include settings that are safe to change.
  17. *
  18. * @todo: Only the field type module knows which settings will affect the
  19. * field's schema, but only the field storage module knows what schema
  20. * changes are permitted once a field already has data. Probably we need an
  21. * easy way for a field type module to ask whether an update to a new schema
  22. * will be allowed without having to build up a fake $prior_field structure
  23. * for hook_field_update_forbid().
  24. *
  25. * @param $field
  26. * The field structure being configured.
  27. * @param $instance
  28. * The instance structure being configured.
  29. * @param $has_data
  30. * TRUE if the field already has data, FALSE if not.
  31. *
  32. * @return
  33. * The form definition for the field settings.
  34. */
  35. function hook_field_settings_form($field, $instance, $has_data) {
  36. $settings = $field['settings'];
  37. $form['max_length'] = array(
  38. '#type' => 'textfield',
  39. '#title' => t('Maximum length'),
  40. '#default_value' => $settings['max_length'],
  41. '#required' => FALSE,
  42. '#element_validate' => array('element_validate_integer_positive'),
  43. '#description' => t('The maximum length of the field in characters. Leave blank for an unlimited size.'),
  44. );
  45. return $form;
  46. }
  47. /**
  48. * Add settings to an instance field settings form.
  49. *
  50. * Invoked from field_ui_field_edit_form() to allow the module defining the
  51. * field to add settings for a field instance.
  52. *
  53. * @param $field
  54. * The field structure being configured.
  55. * @param $instance
  56. * The instance structure being configured.
  57. *
  58. * @return
  59. * The form definition for the field instance settings.
  60. */
  61. function hook_field_instance_settings_form($field, $instance) {
  62. $settings = $instance['settings'];
  63. $form['text_processing'] = array(
  64. '#type' => 'radios',
  65. '#title' => t('Text processing'),
  66. '#default_value' => $settings['text_processing'],
  67. '#options' => array(
  68. t('Plain text'),
  69. t('Filtered text (user selects text format)'),
  70. ),
  71. );
  72. if ($field['type'] == 'text_with_summary') {
  73. $form['display_summary'] = array(
  74. '#type' => 'select',
  75. '#title' => t('Display summary'),
  76. '#options' => array(
  77. t('No'),
  78. t('Yes'),
  79. ),
  80. '#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.'),
  81. '#default_value' => !empty($settings['display_summary']) ? $settings['display_summary'] : 0,
  82. );
  83. }
  84. return $form;
  85. }
  86. /**
  87. * Add settings to a widget settings form.
  88. *
  89. * Invoked from field_ui_field_edit_form() to allow the module defining the
  90. * widget to add settings for a widget instance.
  91. *
  92. * @param $field
  93. * The field structure being configured.
  94. * @param $instance
  95. * The instance structure being configured.
  96. *
  97. * @return
  98. * The form definition for the widget settings.
  99. */
  100. function hook_field_widget_settings_form($field, $instance) {
  101. $widget = $instance['widget'];
  102. $settings = $widget['settings'];
  103. if ($widget['type'] == 'text_textfield') {
  104. $form['size'] = array(
  105. '#type' => 'textfield',
  106. '#title' => t('Size of textfield'),
  107. '#default_value' => $settings['size'],
  108. '#element_validate' => array('element_validate_integer_positive'),
  109. '#required' => TRUE,
  110. );
  111. }
  112. else {
  113. $form['rows'] = array(
  114. '#type' => 'textfield',
  115. '#title' => t('Rows'),
  116. '#default_value' => $settings['rows'],
  117. '#element_validate' => array('element_validate_integer_positive'),
  118. '#required' => TRUE,
  119. );
  120. }
  121. return $form;
  122. }
  123. /**
  124. * Specify the form elements for a formatter's settings.
  125. *
  126. * @param $field
  127. * The field structure being configured.
  128. * @param $instance
  129. * The instance structure being configured.
  130. * @param $view_mode
  131. * The view mode being configured.
  132. * @param $form
  133. * The (entire) configuration form array, which will usually have no use here.
  134. * @param $form_state
  135. * The form state of the (entire) configuration form.
  136. *
  137. * @return
  138. * The form elements for the formatter settings.
  139. */
  140. function hook_field_formatter_settings_form($field, $instance, $view_mode, $form, &$form_state) {
  141. $display = $instance['display'][$view_mode];
  142. $settings = $display['settings'];
  143. $element = array();
  144. if ($display['type'] == 'text_trimmed' || $display['type'] == 'text_summary_or_trimmed') {
  145. $element['trim_length'] = array(
  146. '#title' => t('Length'),
  147. '#type' => 'textfield',
  148. '#size' => 20,
  149. '#default_value' => $settings['trim_length'],
  150. '#element_validate' => array('element_validate_integer_positive'),
  151. '#required' => TRUE,
  152. );
  153. }
  154. return $element;
  155. }
  156. /**
  157. * Return a short summary for the current formatter settings of an instance.
  158. *
  159. * If an empty result is returned, the formatter is assumed to have no
  160. * configurable settings, and no UI will be provided to display a settings
  161. * form.
  162. *
  163. * @param $field
  164. * The field structure.
  165. * @param $instance
  166. * The instance structure.
  167. * @param $view_mode
  168. * The view mode for which a settings summary is requested.
  169. *
  170. * @return
  171. * A string containing a short summary of the formatter settings.
  172. */
  173. function hook_field_formatter_settings_summary($field, $instance, $view_mode) {
  174. $display = $instance['display'][$view_mode];
  175. $settings = $display['settings'];
  176. $summary = '';
  177. if ($display['type'] == 'text_trimmed' || $display['type'] == 'text_summary_or_trimmed') {
  178. $summary = t('Length: @chars chars', array('@chars' => $settings['trim_length']));
  179. }
  180. return $summary;
  181. }
  182. /**
  183. * @} End of "addtogroup field_types".
  184. */

Functions

Namesort descending Description
hook_field_formatter_settings_form Specify the form elements for a formatter's settings.
hook_field_formatter_settings_summary Return a short summary for the current formatter settings of an instance.
hook_field_instance_settings_form Add settings to an instance field settings form.
hook_field_settings_form Add settings to a field settings form.
hook_field_widget_settings_form Add settings to a widget settings form.