Properly handle entity types with only one bundle and no 'real path'
[project/simple_field.git] / 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 */