root / drupal7 / sites / all / modules / field_group / field_group.api.php @ a84ddea4
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Hooks provided by the Field group module.
|
6 |
*
|
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 |
*/
|
460 |
|