root / drupal7 / sites / all / modules / field_group / field_group.api.php @ 27945136
1 | 85ad3d82 | Assos Assos | <?php
|
---|---|---|---|
2 | |||
3 | /**
|
||
4 | * @file
|
||
5 | e9f59589 | Assos Assos | * Hooks provided by the Field Group module.
|
6 | 85ad3d82 | Assos Assos | *
|
7 | * Fieldgroup is a module that will wrap fields and other fieldgroups. Nothing more, nothing less.
|
||
8 | * For this there are formatters we can create on forms and view modes.
|
||
9 | *
|
||
10 | * Some of the elements defined in fieldgroup will be ported to the elements module.
|
||
11 | *
|
||
12 | * DEVELOPERS NOTES
|
||
13 | *
|
||
14 | * - Fieldgroup uses a ''#fieldgroups' property to know what fieldgroups are to be pre_rendered and
|
||
15 | * rendered by the field_group module. This means we need to be sure our groups are in #fieldgroups.
|
||
16 | * #fieldgroups is later merged with the normal #groups that can be used by any other module.
|
||
17 | * This is done to be sure fieldgroup is not taking fieldsets from profile2, commerce line items,
|
||
18 | * commerce user profiles, ... .
|
||
19 | * When trying to merge a programmatically created field wrapper (div, markup, fieldset, ...) into
|
||
20 | * groups, you might consider adding it in #field_groups as well if you want the element processed
|
||
21 | * by fieldgroup.
|
||
22 | */
|
||
23 | |||
24 | /**
|
||
25 | * @addtogroup hooks
|
||
26 | * @{
|
||
27 | */
|
||
28 | |||
29 | |||
30 | /**
|
||
31 | * Javascript hooks
|
||
32 | *
|
||
33 | * Drupal.FieldGroup.Effects.processHook.execute()
|
||
34 | * See field_group.js for the examples for all implemented formatters.
|
||
35 | */
|
||
36 | |||
37 | |||
38 | /**
|
||
39 | * Implements hook_field_group_formatter_info().
|
||
40 | *
|
||
41 | * Define the information on formatters. The formatters are
|
||
42 | * separated by view mode type. We have "form" for all form elements
|
||
43 | * and "display" will be the real view modes (full, teaser, sticky, ...)
|
||
44 | *
|
||
45 | * structure:
|
||
46 | * @code
|
||
47 | * array(
|
||
48 | * 'form' => array(
|
||
49 | * 'fieldset' => array(
|
||
50 | * // required, String with the name of the formatter type.
|
||
51 | * 'label' => t('Fieldset'),
|
||
52 | * // optional, String description of the formatter type.
|
||
53 | * 'description' => t('This is field group that ...'),
|
||
54 | * // required, Array of available formatter options.
|
||
55 | * 'format_types' => array('open', 'collapsible', 'collapsed'),
|
||
56 | * // required, String with default value of the style.
|
||
57 | 'default_formatter' => 'collapsible',
|
||
58 | * // optional, Array with key => default_value pairs.
|
||
59 | * 'instance_settings' => array('key' => 'value'),
|
||
60 | * ),
|
||
61 | * ),
|
||
62 | * 'display' => array(
|
||
63 | * 'fieldset' => array(
|
||
64 | * // required, String with the name of the formatter type.
|
||
65 | * 'label' => t('Fieldset'),
|
||
66 | * // optional, String description of the formatter type.
|
||
67 | * 'description' => t('This is field group that ...'),
|
||
68 | * // required, Array of available formatter options.
|
||
69 | * 'format_types' => array('open', 'collapsible', 'collapsed'),
|
||
70 | * // required, String with default value of the style.
|
||
71 | 'default_formatter' => 'collapsible',
|
||
72 | * // optional, Array with key => default_value pairs.
|
||
73 | * 'instance_settings' => array('key' => 'value'),
|
||
74 | * ),
|
||
75 | * ),
|
||
76 | * ),
|
||
77 | * @endcode
|
||
78 | *
|
||
79 | * @return $formatters
|
||
80 | * A collection of available formatting html controls for form
|
||
81 | * and display overview type.
|
||
82 | *
|
||
83 | * @see field_group_field_group_formatter_info()
|
||
84 | */
|
||
85 | function hook_field_group_formatter_info() { |
||
86 | return array( |
||
87 | 'form' => array( |
||
88 | 'fieldset' => array( |
||
89 | 'label' => t('Fieldset'), |
||
90 | 'description' => t('This fieldgroup renders the inner content in a fieldset with the title as legend.'), |
||
91 | 'format_types' => array('open', 'collapsible', 'collapsed'), |
||
92 | 'instance_settings' => array('classes' => ''), |
||
93 | 'default_formatter' => 'collapsible', |
||
94 | ), |
||
95 | ), |
||
96 | 'display' => array( |
||
97 | 'div' => array( |
||
98 | 'label' => t('Div'), |
||
99 | 'description' => t('This fieldgroup renders the inner content in a simple div with the title as legend.'), |
||
100 | 'format_types' => array('open', 'collapsible', 'collapsed'), |
||
101 | 'instance_settings' => array('effect' => 'none', 'speed' => 'fast', 'classes' => ''), |
||
102 | 'default_formatter' => 'collapsible', |
||
103 | ), |
||
104 | ), |
||
105 | ); |
||
106 | } |
||
107 | |||
108 | /**
|
||
109 | * Implements hook_field_group_format_settings().
|
||
110 | *
|
||
111 | * Defines configuration widget for the settings on a field group
|
||
112 | * formatter. Eache formatter can have different elements and storage.
|
||
113 | *
|
||
114 | * @params Object $group The group object.
|
||
115 | * @return Array $form The form element for the format settings.
|
||
116 | */
|
||
117 | function hook_field_group_format_settings($group) { |
||
118 | // Add a wrapper for extra settings to use by others.
|
||
119 | $form = array( |
||
120 | 'instance_settings' => array( |
||
121 | '#tree' => TRUE, |
||
122 | '#weight' => 2, |
||
123 | ), |
||
124 | ); |
||
125 | |||
126 | $field_group_types = field_group_formatter_info();
|
||
127 | $mode = $group->mode == 'form' ? 'form' : 'display'; |
||
128 | $formatter = $field_group_types[$mode][$group->format_type]; |
||
129 | |||
130 | // Add the required formatter type selector.
|
||
131 | if (isset($formatter['format_types'])) { |
||
132 | $form['formatter'] = array( |
||
133 | '#title' => t('Fieldgroup settings'), |
||
134 | '#type' => 'select', |
||
135 | '#options' => drupal_map_assoc($formatter['format_types']), |
||
136 | '#default_value' => isset($group->format_settings['formatter']) ? $group->format_settings['formatter'] : $formatter['default_formatter'], |
||
137 | '#weight' => 1, |
||
138 | ); |
||
139 | } |
||
140 | if ($mode == 'form') { |
||
141 | $form['instance_settings']['required_fields'] = array( |
||
142 | '#type' => 'checkbox', |
||
143 | '#title' => t('Mark group for required fields.'), |
||
144 | '#default_value' => isset($group->format_settings['instance_settings']['required_fields']) ? $group->format_settings['instance_settings']['required_fields'] : (isset($formatter['instance_settings']['required_fields']) ? $formatter['instance_settings']['required_fields'] : ''), |
||
145 | '#weight' => 2, |
||
146 | ); |
||
147 | } |
||
148 | $form['instance_settings']['classes'] = array( |
||
149 | '#title' => t('Extra CSS classes'), |
||
150 | '#type' => 'textfield', |
||
151 | '#default_value' => isset($group->format_settings['instance_settings']['classes']) ? $group->format_settings['instance_settings']['classes'] : (isset($formatter['instance_settings']['classes']) ? $formatter['instance_settings']['classes'] : ''), |
||
152 | '#weight' => 3, |
||
153 | '#element_validate' => array('field_group_validate_css_class'), |
||
154 | ); |
||
155 | $form['instance_settings']['description'] = array( |
||
156 | '#title' => t('Description'), |
||
157 | '#type' => 'textarea', |
||
158 | '#default_value' => isset($group->format_settings['instance_settings']['description']) ? $group->format_settings['instance_settings']['description'] : (isset($formatter['instance_settings']['description']) ? $formatter['instance_settings']['description'] : ''), |
||
159 | '#weight' => 0, |
||
160 | ); |
||
161 | |||
162 | // Add optional instance_settings.
|
||
163 | switch ($group->format_type) { |
||
164 | case 'div': |
||
165 | $form['instance_settings']['effect'] = array( |
||
166 | '#title' => t('Effect'), |
||
167 | '#type' => 'select', |
||
168 | '#options' => array('none' => t('None'), 'blind' => t('Blind')), |
||
169 | '#default_value' => isset($group->format_settings['instance_settings']['effect']) ? $group->format_settings['instance_settings']['effect'] : $formatter['instance_settings']['effect'], |
||
170 | '#weight' => 2, |
||
171 | ); |
||
172 | $form['instance_settings']['speed'] = array( |
||
173 | '#title' => t('Speed'), |
||
174 | '#type' => 'select', |
||
175 | '#options' => array('none' => t('None'), 'slow' => t('Slow'), 'fast' => t('Fast')), |
||
176 | '#default_value' => isset($group->format_settings['instance_settings']['speed']) ? $group->format_settings['instance_settings']['speed'] : $formatter['instance_settings']['speed'], |
||
177 | '#weight' => 3, |
||
178 | ); |
||
179 | break;
|
||
180 | case 'fieldset': |
||
181 | $form['instance_settings']['classes'] = array( |
||
182 | '#title' => t('Extra CSS classes'), |
||
183 | '#type' => 'textfield', |
||
184 | '#default_value' => isset($group->format_settings['instance_settings']['classes']) ? $group->format_settings['instance_settings']['classes'] : $formatter['instance_settings']['classes'], |
||
185 | '#weight' => 3, |
||
186 | '#element_validate' => array('field_group_validate_css_class'), |
||
187 | ); |
||
188 | break;
|
||
189 | case 'tabs': |
||
190 | case 'htabs': |
||
191 | case 'accordion': |
||
192 | unset($form['instance_settings']['description']); |
||
193 | if (isset($form['instance_settings']['required_fields'])) { |
||
194 | unset($form['instance_settings']['required_fields']); |
||
195 | } |
||
196 | break;
|
||
197 | case 'tab': |
||
198 | case 'htab': |
||
199 | case 'accordion-item': |
||
200 | default:
|
||
201 | } |
||
202 | |||
203 | return $form; |
||
204 | } |
||
205 | |||
206 | /**
|
||
207 | * Implements hook_field_group_pre_render().
|
||
208 | *
|
||
209 | * This function gives you the oppertunity to create the given
|
||
210 | * wrapper element that can contain the fields.
|
||
211 | * In the example beneath, some variables are prepared and used when building the
|
||
212 | * actual wrapper element. All elements in drupal fapi can be used.
|
||
213 | *
|
||
214 | * Note that at this point, the field group has no notion of the fields in it.
|
||
215 | *
|
||
216 | * There is also an alternative way of handling this. The default implementation
|
||
217 | * within field_group calls "field_group_pre_render_<format_type>".
|
||
218 | * @see field_group_pre_render_fieldset.
|
||
219 | *
|
||
220 | * @param Array $elements by address.
|
||
221 | * @param Object $group The Field group info.
|
||
222 | */
|
||
223 | function hook_field_group_pre_render(& $element, $group, & $form) { |
||
224 | |||
225 | // You can prepare some variables to use in the logic.
|
||
226 | $view_mode = isset($form['#view_mode']) ? $form['#view_mode'] : 'form'; |
||
227 | $id = $form['#entity_type'] . '_' . $form['#bundle'] . '_' . $view_mode . '_' . $group->group_name; |
||
228 | |||
229 | // Each formatter type can have whole different set of element properties.
|
||
230 | switch ($group->format_type) { |
||
231 | |||
232 | // Normal or collapsible div.
|
||
233 | case 'div': |
||
234 | $effect = isset($group->format_settings['instance_settings']['effect']) ? $group->format_settings['instance_settings']['effect'] : 'none'; |
||
235 | $speed = isset($group->format_settings['instance_settings']['speed']) ? $group->format_settings['instance_settings']['speed'] : 'none'; |
||
236 | $add = array( |
||
237 | '#type' => 'markup', |
||
238 | '#weight' => $group->weight, |
||
239 | '#id' => $id, |
||
240 | ); |
||
241 | $classes .= " speed-$speed effect-$effect"; |
||
242 | if ($group->format_settings['formatter'] != 'open') { |
||
243 | $add['#prefix'] = '<div class="field-group-format ' . $classes . '"> |
||
244 | <span class="field-group-format-toggler">' . check_plain(t($group->label)) . '</span> |
||
245 | <div class="field-group-format-wrapper" style="display: none;">';
|
||
246 | $add['#suffix'] = '</div></div>'; |
||
247 | } |
||
248 | else {
|
||
249 | $add['#prefix'] = '<div class="field-group-format ' . $group->group_name . ' ' . $classes . '">'; |
||
250 | $add['#suffix'] = '</div>'; |
||
251 | } |
||
252 | if (!empty($description)) { |
||
253 | $add['#prefix'] .= '<div class="description">' . $description . '</div>'; |
||
254 | } |
||
255 | $element += $add; |
||
256 | |||
257 | if ($effect == 'blind') { |
||
258 | drupal_add_library('system', 'effects.blind'); |
||
259 | } |
||
260 | |||
261 | break;
|
||
262 | break;
|
||
263 | } |
||
264 | } |
||
265 | |||
266 | /**
|
||
267 | * Implements hook_field_group_pre_render().
|
||
268 | *
|
||
269 | * Function that fungates as last resort to alter the pre_render build.
|
||
270 | */
|
||
271 | function hook_field_group_pre_render_alter(&$element, $group, & $form) { |
||
272 | |||
273 | if ($group->format_type == 'htab') { |
||
274 | $element['#theme_wrappers'] = array('my_horizontal_tab'); |
||
275 | } |
||
276 | |||
277 | } |
||
278 | |||
279 | /**
|
||
280 | * Implements hook_field_group_build_pre_render_alter().
|
||
281 | *
|
||
282 | * Function that fungates as last resort where you can alter things. It is
|
||
283 | * expected that when you need this function, you have most likely a very custom
|
||
284 | * case or it is a fix that can be put in field_group core.
|
||
285 | *
|
||
286 | * @param Array $elements by address.
|
||
287 | */
|
||
288 | function hook_field_group_build_pre_render_alter(& $element) { |
||
289 | |||
290 | // Prepare variables.
|
||
291 | $display = isset($element['#view_mode']); |
||
292 | $groups = array_keys($element['#groups']); |
||
293 | |||
294 | // Example from field_group itself to unset empty elements.
|
||
295 | if ($display) { |
||
296 | foreach (element_children($element) as $name) { |
||
297 | if (in_array($name, $groups)) { |
||
298 | if (field_group_field_group_is_empty($element[$name], $groups)) { |
||
299 | unset($element[$name]); |
||
300 | } |
||
301 | } |
||
302 | } |
||
303 | } |
||
304 | |||
305 | // You might include additional javascript files and stylesheets.
|
||
306 | $element['#attached']['js'][] = drupal_get_path('module', 'field_group') . '/field_group.js'; |
||
307 | $element['#attached']['css'][] = drupal_get_path('module', 'field_group') . '/field_group.css'; |
||
308 | |||
309 | } |
||
310 | |||
311 | /**
|
||
312 | * Implements hook_field_group_format_summary().
|
||
313 | *
|
||
314 | * Place to override or change default summary behavior. In most
|
||
315 | * cases the implementation of field group itself will be enough.
|
||
316 | *
|
||
317 | * TODO It might be better to change this hook with already created summaries,
|
||
318 | * giving the ability to alter or add it later on.
|
||
319 | */
|
||
320 | function hook_field_group_format_summary($group) { |
||
321 | $output = ''; |
||
322 | // Create additional summary or change the default setting.
|
||
323 | return $output; |
||
324 | } |
||
325 | |||
326 | /**
|
||
327 | * Implement hook_ctools_plugin_api().
|
||
328 | * This hook is needed to let ctools know about exportables.
|
||
329 | * If you create field groups by using hook_field_group_info, you
|
||
330 | * will need to include the ctools api hook as well.
|
||
331 | */
|
||
332 | function hook_ctools_plugin_api($module, $api) { |
||
333 | if ($module == 'field_group' && $api == 'field_group') { |
||
334 | return array('version' => 1); |
||
335 | } |
||
336 | } |
||
337 | |||
338 | /**
|
||
339 | * Implements hook_field_group_info().
|
||
340 | * Don't forget to include the ctools hook to notify that
|
||
341 | * your modules has field group exports.
|
||
342 | * @see hook_ctools_plugin_api.
|
||
343 | */
|
||
344 | function hook_field_group_info() { |
||
345 | |||
346 | } |
||
347 | |||
348 | /**
|
||
349 | * Alter the field group definitions provided by other modules.
|
||
350 | *
|
||
351 | * @param array $groups
|
||
352 | * Reference to an array of field group definition objects.
|
||
353 | */
|
||
354 | function hook_field_group_info_alter(&$groups) { |
||
355 | if (!empty($groups['group_issue_metadata|node|project_issue|form'])) { |
||
356 | $groups['group_issue_metadata|node|project_issue|form']->data['children'][] = 'taxonomy_vocabulary_9'; |
||
357 | } |
||
358 | } |
||
359 | |||
360 | /**
|
||
361 | * Implements hook_field_group_update_field_group().
|
||
362 | *
|
||
363 | * This hook is invoked by ctools export API.
|
||
364 | * Note that this is used by ctools and the group could occasional be
|
||
365 | * the group ID.
|
||
366 | *
|
||
367 | * @param $object $group
|
||
368 | * The FieldGroup object.
|
||
369 | */
|
||
370 | function hook_field_group_update_field_group($group) { |
||
371 | // Delete extra data depending on the group.
|
||
372 | } |
||
373 | |||
374 | /**
|
||
375 | * Implements hook_field_group_delete_field_group().
|
||
376 | *
|
||
377 | * This hook is invoked by ctools export API.
|
||
378 | *
|
||
379 | * @param $object $group
|
||
380 | * The FieldGroup object.
|
||
381 | */
|
||
382 | function hook_field_group_delete_field_group($group) { |
||
383 | // Delete extra data depending on the group.
|
||
384 | } |
||
385 | |||
386 | /**
|
||
387 | * Implements hook_field_group_create_field_group().
|
||
388 | *
|
||
389 | * This hook is invoked by ctools export API.
|
||
390 | *
|
||
391 | * @param $object $group
|
||
392 | * The FieldGroup object.
|
||
393 | */
|
||
394 | function hook_field_group_create_field_group($group) { |
||
395 | // Create extra data depending on the group.
|
||
396 | } |
||
397 | |||
398 | |||
399 | |||
400 | /**
|
||
401 | * @} End of "addtogroup hooks".
|
||
402 | */
|
||
403 | |||
404 | |||
405 | |||
406 | /**
|
||
407 | * @addtogroup utility functions
|
||
408 | * @{
|
||
409 | */
|
||
410 | |||
411 | /**
|
||
412 | * Get the groups for a given entity type, bundle and view mode.
|
||
413 | *
|
||
414 | * @param String $entity_type
|
||
415 | * The Entity type where field groups are requested.
|
||
416 | * @param String $bundle
|
||
417 | * The entity bundle for the field groups.
|
||
418 | * @param String $view_mode
|
||
419 | * The view mode scope for the field groups.
|
||
420 | *
|
||
421 | * @see field_group_read_groups()
|
||
422 | * @see ctools_export_crud_load()
|
||
423 | * @see ctools_export_crud_load_all()
|
||
424 | * @see ctools_export_crud_delete()
|
||
425 | * @see ctools_export_crud_save()
|
||
426 | */
|
||
427 | function field_group_info_groups($entity_type = NULL, $bundle = NULL, $view_mode = NULL, $reset = FALSE) { |
||
428 | // This function caches the result and delegates to field_group_read_groups.
|
||
429 | } |
||
430 | |||
431 | /**
|
||
432 | * Get the groups for the given parameters, uncached.
|
||
433 | *
|
||
434 | * @param Array $params
|
||
435 | * The Entity type where field groups are requested.
|
||
436 | * @param $enabled
|
||
437 | * Return enabled or disabled groups.*
|
||
438 | *
|
||
439 | * @see field_group_info_groups()
|
||
440 | * @see ctools_export_load_object()
|
||
441 | */
|
||
442 | function field_group_read_groups($conditions = array(), $enabled = TRUE) { |
||
443 | // This function loads the requested groups through ctools export api.
|
||
444 | } |
||
445 | |||
446 | /**
|
||
447 | * Hides field groups including children in a render array.
|
||
448 | *
|
||
449 | * @param array $element
|
||
450 | * A render array. Can be a form, node, user, ...
|
||
451 | * @param array $group_names
|
||
452 | * An array of field group names that should be hidden.
|
||
453 | */
|
||
454 | function field_group_hide_field_groups(&$element, $group_names) { |
||
455 | } |
||
456 | |||
457 | /**
|
||
458 | * @} End of "addtogroup utility functions".
|
||
459 | */
|