simple_field.api.php

   1 <?php
   2 /**
   3  * @file
   4  * Hooks provided by the Simple Field module.
   5  */
   6
   7 /**
   8  * @addtogroup hooks
   9  * @{
  10  */
  11
  12 /**
  13  * Allow modules to specify custom types of simple fields.
  14  *
  15  * @return
  16  *   An array whose keys are simple field type names and whose values are arrays
  17  *   containing the keys. All optional except 'field'.
  18  *   - field: The Field module field type machine name.
  19  *   - label: The short label for this simple field type or the
  20  *     machine name if not specified.
  21  *   - help: The long description of the behavior of the simple
  22  *     field type or blank if not specified.
  23  *   - widget: The Field module widget type. Will use field default
  24  *     if not specified.
  25  *   - formatter: The Field module formatter type. Will use the field
  26  *     default formatter if not specified.
  27  *   - cardinality: The cardinality of the field. Unlimited if blank.
  28  *   - defaults: An array of settings to override the default Field
  29  *     module settings. Keyed by the type of setting.
  30  *     - field_settings: Settings to override values returned from calling
  31  *       field_info_field_settings($field_type);
  32  *     - instance_settings: Settings to override values returned from calling
  33  *       field_info_instance_settings($field_type);
  34  *     - widget_settings: Settings to override values returned from calling
  35  *       field_info_widget_settings($widget_type);
  36  *     - formatter_settings: Settings to override values returned from calling
  37  *       field_info_formatter_settings($formatter_type);
  38  */
  39 function hook_simple_field_type_info() {
  40   return array(
  41     'simple_field_yesno' => array(
  42       // There are a ton more options for this, but they are set to defaults.
  43       // @see simple_field_type_info()
  44       'label' => t('Yes/No'),
  45       'help' => t('Display a set of Yes and No radio buttons to allow the user a boolean choice.'),
  46       'field' => 'list_boolean',
  47       'cardinality' => 1,
  48       'defaults' => array(
  49         'field_settings' => array(
  50           'allowed_values' => array(
  51             1 => 'Yes',
  52             0 => 'No',
  53           ),
  54         ),
  55       ),
  56     ),
  57     'simple_field_multichoice_single' => array(
  58       'label' => t('Multiple Choice (Choose 1 Options)'),
  59       'help' => t('Enter a list of options and allow the user to select a single options.'),
  60       'field' => 'list_text',
  61       'widget' => 'options_buttons',
  62       'cardinality' => 1,
  63     ),
  64     'simple_field_multichoice_multi' => array(
  65       'label' => t('Multiple Choice (Choose many Options)'),
  66       'help' => t('Enter a list of options and allow the user to select as many as they would like.'),
  67       'field' => 'list_text',
  68       'widget' => 'options_buttons',
  69       'cardinality' => FIELD_CARDINALITY_UNLIMITED,
  70     ),
  71     'simple_field_short_answer' => array(
  72       'label' => t('Short Answer'),
  73       'help' => t('Allow the user to enter a single line of text.'),
  74       'cardinality' => 1,
  75       'field' => 'text',
  76     ),
  77     'simple_field_long_answer' => array(
  78       'label' => t('Long Answer'),
  79       'help' => t('Allow the user to enter a large block of text.'),
  80       'cardinality' => 1,
  81       'field' => 'text_long',
  82       'widget' => 'text_textarea',
  83     ),
  84     'simple_field_single_date' => array(
  85       'label' => t('Date'),
  86       'help' => t('Allow the user to enter a single Date value.'),
  87       'field' => 'datestamp',
  88       'widget' => 'date_text',
  89       'cardinality' => 1,
  90       'defaults' => array(
  91         'field_settings' => array(
  92           'granularity' => array(
  93             'year' => 'year',
  94             'month' => 'month',
  95             'day' => 'day',
  96           ),
  97           'tz_handling' => 'none',
  98         ),
  99         'instance_settings' => array(
 100           'default_value' => 'blank',
 101         ),
 102         'widget_settings' => array(
 103           'input_format_custom' => 'Y-m-d',
 104         ),
 105       ),
 106     ),
 107     'simple_field_date_range' => array(
 108       'label' => t('Date Range'),
 109       'help' => t('Allow the user to enter a Date range with a beginning and ending date.'),
 110       'field' => 'datestamp',
 111       'widget' => 'date_text',
 112       'cardinality' => 1,
 113       'defaults' => array(
 114         'field_settings' => array(
 115           'todate' => 'required',
 116           'granularity' => array(
 117             'year' => 'year',
 118             'month' => 'month',
 119             'day' => 'day',
 120           ),
 121           'tz_handling' => 'none',
 122         ),
 123         'instance_settings' => array(
 124           'default_value' => 'blank',
 125         ),
 126         'widget_settings' => array(
 127           'input_format_custom' => 'Y-m-d',
 128         ),
 129       ),
 130     ),
 131     'simple_field_integer' => array(
 132       'label' => t('Integer'),
 133       'help' => t('Allow the user to enter a single single integer value.'),
 134       'cardinality' => 1,
 135       'field' => 'number_integer',
 136     ),
 137   );
 138 }
 139
 140 /**
 141  * Allow modules to add elements to the simple field form.
 142  *
 143  * This hook allows modules to provide form elements in order to allow users to
 144  * change field settings. The hook is only called on the module that provided
 145  * the simple field type, so any module looking to alter these settings should
 146  * use hook_form_alter.
 147  *
 148  * @param SimpleField $simplefield
 149  *   The simple_field entity that is being added/edited by this form.
 150  * @param bool $has_data
 151  *   Boolean indicating whether this field has data associated with it. This is
 152  *   used to disable modification of certain settings which cannot be changes
 153  *   once the field schema becomes unchangeable.
 154  *
 155  * @return
 156  *   A renderable form array which will be appended to the add/edit form. The
 157  *   form elements must be set up so that the settings can be properly split up
 158  *   when saved. However you want to structure the form, in the end
 159  *   $form_state['values'] must contain 'field_settings', 'instance_settings',
 160  *   'widget_settings' and/or 'formatter_settings' keys, and the values must be
 161  *   in the right place so they can be properly merged back into their
 162  *   respecting settings arrays.
 163  */
 164 function hook_simple_field_type_form($simplefield, $has_data) {
 165   $form = array();
 166   $type_info = $simplefield->getTypeInfo();
 167   $field_settings = $simplefield->getSettings('field');
 168
 169   switch ($type_info['type']) {
 170     case 'simple_field_yesno':
 171       break;
 172     case 'simple_field_multichoice_single':
 173     case 'simple_field_multichoice_multi':
 174       $form['field_settings']['somefieldsetting'] = array(
 175         '#type' => 'textfield',
 176         '#title' => t('Field specific setting'),
 177         '#default_value' => $field_setting['somefieldsetting'],
 178       );
 179       break;
 180     case 'simple_field_short_answer':
 181     case 'simple_field_long_answer':
 182     case 'simple_field_single_date':
 183     case 'simple_field_date_range':
 184   }
 185
 186   return $form;
 187 }
 188
 189 /**
 190  * @} End of "addtogroup hooks".
 191  */