upgrade to OpenPublish 7.x-1.0-alpha9
[eupraxis:fsrn.git] / openpublish / modules / field / field.api.php
1 <?php
2
3 /**
4  * @addtogroup hooks
5  * @{
6  */
7
8 /**
9  * Exposes "pseudo-field" components on fieldable entities.
10  *
11  * Field UI's "Manage fields" and "Manage display" pages let users re-order
12  * fields, but also non-field components. For nodes, these include the title,
13  * poll choices, and other elements exposed by modules through hook_form() or
14  * hook_form_alter().
15  *
16  * Fieldable entities or modules that want to have their components supported
17  * should expose them using this hook. The user-defined settings (weight,
18  * visible) are automatically applied on rendered forms and displayed
19  * entities in a #pre_render callback added by field_attach_form() and
20  * field_attach_view().
21  *
22  * @see _field_extra_fields_pre_render()
23  * @see hook_field_extra_fields_alter()
24  *
25  * @return
26  *   A nested array of 'pseudo-field' components. Each list is nested within
27  *   the following keys: entity type, bundle name, context (either 'form' or
28  *   'display'). The keys are the name of the elements as appearing in the
29  *   renderable array (either the entity form or the displayed entity). The
30  *   value is an associative array:
31  *   - label: The human readable name of the component.
32  *   - description: A short description of the component contents.
33  *   - weight: The default weight of the element.
34  */
35 function hook_field_extra_fields() {
36   $extra['node']['poll'] = array(
37     'form' => array(
38       'choice_wrapper' => array(
39         'label' => t('Poll choices'),
40         'description' => t('Poll choices'),
41         'weight' => -4,
42       ),
43       'settings' => array(
44         'label' => t('Poll settings'),
45         'description' => t('Poll module settings'),
46         'weight' => -3,
47       ),
48     ),
49     'display' => array(
50       'poll_view_voting' => array(
51         'label' => t('Poll vote'),
52         'description' => t('Poll vote'),
53         'weight' => 0,
54       ),
55       'poll_view_results' => array(
56         'label' => t('Poll results'),
57         'description' => t('Poll results'),
58         'weight' => 0,
59       ),
60     )
61   );
62
63   return $extra;
64 }
65
66 /**
67  * Alter "pseudo-field" components on fieldable entities.
68  *
69  * @param $info
70  *   The associative array of 'pseudo-field' components.
71  *
72  * @see hook_field_extra_fields()
73  */
74 function hook_field_extra_fields_alter(&$info) {
75   // Force node title to always be at the top of the list by default.
76   foreach (node_type_get_types() as $bundle) {
77     if (isset($info['node'][$bundle->type]['form']['title'])) {
78       $info['node'][$bundle->type]['form']['title']['weight'] = -20;
79     }
80   }
81 }
82
83 /**
84  * @defgroup field_types Field Types API
85  * @{
86  * Define field types.
87  *
88  * In the Field API, each field has a type, which determines what kind of data
89  * (integer, string, date, etc.) the field can hold, which settings it provides,
90  * and so on. The data type(s) accepted by a field are defined in
91  * hook_field_schema(); other basic properties of a field are defined in
92  * hook_field_info(). The other hooks below are called by the Field Attach API
93  * to perform field-type-specific actions.
94  *
95  * The Field Types API also defines two kinds of pluggable handlers: widgets
96  * and formatters. @link field_widget Widgets @endlink specify how the field
97  * appears in edit forms, while @link field_formatter formatters @endlink
98  * specify how the field appears in displayed entities.
99  *
100  * A third kind of pluggable handlers, storage backends, is defined by the
101  * @link field_storage Field Storage API @endlink.
102  *
103  * See @link field Field API @endlink for information about the other parts of
104  * the Field API.
105  */
106
107 /**
108  * Define Field API field types.
109  *
110  * @return
111  *   An array whose keys are field type names and whose values are arrays
112  *   describing the field type, with the following key/value pairs:
113  *   - label: The human-readable name of the field type.
114  *   - description: A short description for the field type.
115  *   - settings: An array whose keys are the names of the settings available
116  *     for the field type, and whose values are the default values for those
117  *     settings.
118  *   - instance_settings: An array whose keys are the names of the settings
119  *     available for instances of the field type, and whose values are the
120  *     default values for those settings. Instance-level settings can have
121  *     different values on each field instance, and thus allow greater
122  *     flexibility than field-level settings. It is recommended to put settings
123  *     at the instance level whenever possible. Notable exceptions: settings
124  *     acting on the schema definition, or settings that Views needs to use
125  *     across field instances (for example, the list of allowed values).
126  *   - default_widget: The machine name of the default widget to be used by
127  *     instances of this field type, when no widget is specified in the
128  *     instance definition. This widget must be available whenever the field
129  *     type is available (i.e. provided by the field type module, or by a module
130  *     the field type module depends on).
131  *   - default_formatter: The machine name of the default formatter to be used
132  *     by instances of this field type, when no formatter is specified in the
133  *     instance definition. This formatter must be available whenever the field
134  *     type is available (i.e. provided by the field type module, or by a module
135  *     the field type module depends on).
136  *   - no_ui: (optional) A boolean specifying that users should not be allowed
137  *     to create fields and instances of this field type through the UI. Such
138  *     fields can only be created programmatically with field_create_field()
139  *     and field_create_instance(). Defaults to FALSE.
140  *
141  * @see hook_field_info_alter()
142  */
143 function hook_field_info() {
144   return array(
145     'text' => array(
146       'label' => t('Text'),
147       'description' => t('This field stores varchar text in the database.'),
148       'settings' => array('max_length' => 255),
149       'instance_settings' => array('text_processing' => 0),
150       'default_widget' => 'text_textfield',
151       'default_formatter' => 'text_default',
152     ),
153     'text_long' => array(
154       'label' => t('Long text'),
155       'description' => t('This field stores long text in the database.'),
156       'settings' => array('max_length' => ''),
157       'instance_settings' => array('text_processing' => 0),
158       'default_widget' => 'text_textarea',
159       'default_formatter' => 'text_default',
160     ),
161     'text_with_summary' => array(
162       'label' => t('Long text and summary'),
163       'description' => t('This field stores long text in the database along with optional summary text.'),
164       'settings' => array('max_length' => ''),
165       'instance_settings' => array('text_processing' => 1, 'display_summary' => 0),
166       'default_widget' => 'text_textarea_with_summary',
167       'default_formatter' => 'text_summary_or_trimmed',
168     ),
169   );
170 }
171
172 /**
173  * Perform alterations on Field API field types.
174  *
175  * @param $info
176  *   Array of information on field types exposed by hook_field_info()
177  *   implementations.
178  */
179 function hook_field_info_alter(&$info) {
180   // Add a setting to all field types.
181   foreach ($info as $field_type => $field_type_info) {
182     $info[$field_type]['settings'] += array(
183       'mymodule_additional_setting' => 'default value',
184     );
185   }
186
187   // Change the default widget for fields of type 'foo'.
188   if (isset($info['foo'])) {
189     $info['foo']['default widget'] = 'mymodule_widget';
190   }
191 }
192
193 /**
194  * Define the Field API schema for a field structure.
195  *
196  * This hook MUST be defined in .install for it to be detected during
197  * installation and upgrade.
198  *
199  * @param $field
200  *   A field structure.
201  *
202  * @return
203  *   An associative array with the following keys:
204  *   - columns: An array of Schema API column specifications, keyed by column
205  *     name. This specifies what comprises a value for a given field. For
206  *     example, a value for a number field is simply 'value', while a value for
207  *     a formatted text field is the combination of 'value' and 'format'. It is
208  *     recommended to avoid having the column definitions depend on field
209  *     settings when possible. No assumptions should be made on how storage
210  *     engines internally use the original column name to structure their
211  *     storage.
212  *   - indexes: (optional) An array of Schema API indexes definitions. Only
213  *     columns that appear in the 'columns' array are allowed. Those indexes
214  *     will be used as default indexes. Callers of field_create_field() can
215  *     specify additional indexes, or, at their own risk, modify the default
216  *     indexes specified by the field-type module. Some storage engines might
217  *     not support indexes.
218  *   - foreign keys: (optional) An array of Schema API foreign keys
219  *     definitions.
220  */
221 function hook_field_schema($field) {
222   if ($field['type'] == 'text_long') {
223     $columns = array(
224       'value' => array(
225         'type' => 'text',
226         'size' => 'big',
227         'not null' => FALSE,
228       ),
229     );
230   }
231   else {
232     $columns = array(
233       'value' => array(
234         'type' => 'varchar',
235         'length' => $field['settings']['max_length'],
236         'not null' => FALSE,
237       ),
238     );
239   }
240   $columns += array(
241     'format' => array(
242       'type' => 'varchar',
243       'length' => 255,
244       'not null' => FALSE,
245     ),
246   );
247   return array(
248     'columns' => $columns,
249     'indexes' => array(
250       'format' => array('format'),
251     ),
252     'foreign keys' => array(
253       'format' => array(
254         'table' => 'filter_format',
255         'columns' => array('format' => 'format'),
256       ),
257     ),
258   );
259 }
260
261 /**
262  * Define custom load behavior for this module's field types.
263  *
264  * Unlike most other field hooks, this hook operates on multiple entities. The
265  * $entities, $instances and $items parameters are arrays keyed by entity ID.
266  * For performance reasons, information for all available entity should be
267  * loaded in a single query where possible.
268  *
269  * Note that the changes made to the field values get cached by the field cache
270  * for subsequent loads. You should never use this hook to load fieldable
271  * entities, since this is likely to cause infinite recursions when
272  * hook_field_load() is run on those as well. Use
273  * hook_field_formatter_prepare_view() instead.
274  *
275  * Make changes or additions to field values by altering the $items parameter by
276  * reference. There is no return value.
277  *
278  * @param $entity_type
279  *   The type of $entity.
280  * @param $entities
281  *   Array of entities being loaded, keyed by entity ID.
282  * @param $field
283  *   The field structure for the operation.
284  * @param $instances
285  *   Array of instance structures for $field for each entity, keyed by entity
286  *   ID.
287  * @param $langcode
288  *   The language code associated with $items.
289  * @param $items
290  *   Array of field values already loaded for the entities, keyed by entity ID.
291  *   Store your changes in this parameter (passed by reference).
292  * @param $age
293  *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
294  *   FIELD_LOAD_REVISION to load the version indicated by each entity.
295  */
296 function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) {
297   // Sample code from text.module: precompute sanitized strings so they are
298   // stored in the field cache.
299   foreach ($entities as $id => $entity) {
300     foreach ($items[$id] as $delta => $item) {
301       // Only process items with a cacheable format, the rest will be handled
302       // by formatters if needed.
303       if (empty($instances[$id]['settings']['text_processing']) || filter_format_allowcache($item['format'])) {
304         $items[$id][$delta]['safe_value'] = isset($item['value']) ? _text_sanitize($instances[$id], $langcode, $item, 'value') : '';
305         if ($field['type'] == 'text_with_summary') {
306           $items[$id][$delta]['safe_summary'] = isset($item['summary']) ? _text_sanitize($instances[$id], $langcode, $item, 'summary') : '';
307         }
308       }
309     }
310   }
311 }
312
313 /**
314  * Prepare field values prior to display.
315  *
316  * This hook is invoked before the field values are handed to formatters
317  * for display, and runs before the formatters' own
318  * hook_field_formatter_prepare_view().
319  *
320  * Unlike most other field hooks, this hook operates on multiple entities. The
321  * $entities, $instances and $items parameters are arrays keyed by entity ID.
322  * For performance reasons, information for all available entities should be
323  * loaded in a single query where possible.
324  *
325  * Make changes or additions to field values by altering the $items parameter by
326  * reference. There is no return value.
327  *
328  * @param $entity_type
329  *   The type of $entity.
330  * @param $entities
331  *   Array of entities being displayed, keyed by entity ID.
332  * @param $field
333  *   The field structure for the operation.
334  * @param $instances
335  *   Array of instance structures for $field for each entity, keyed by entity
336  *   ID.
337  * @param $langcode
338  *   The language associated to $items.
339  * @param $items
340  *   $entity->{$field['field_name']}, or an empty array if unset.
341  */
342 function hook_field_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items) {
343   // Sample code from image.module: if there are no images specified at all,
344   // use the default image.
345   foreach ($entities as $id => $entity) {
346     if (empty($items[$id]) && $field['settings']['default_image']) {
347       if ($file = file_load($field['settings']['default_image'])) {
348         $items[$id][0] = (array) $file + array(
349           'is_default' => TRUE,
350           'alt' => '',
351           'title' => '',
352         );
353       }
354     }
355   }
356 }
357
358 /**
359  * Validate this module's field data.
360  *
361  * If there are validation problems, add to the $errors array (passed by
362  * reference). There is no return value.
363  *
364  * @param $entity_type
365  *   The type of $entity.
366  * @param $entity
367  *   The entity for the operation.
368  * @param $field
369  *   The field structure for the operation.
370  * @param $instance
371  *   The instance structure for $field on $entity's bundle.
372  * @param $langcode
373  *   The language associated with $items.
374  * @param $items
375  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
376  * @param $errors
377  *   The array of errors (keyed by field name, language code, and delta) that
378  *   have already been reported for the entity. The function should add its
379  *   errors to this array. Each error is an associative array with the following
380  *   keys and values:
381  *   - error: An error code (should be a string prefixed with the module name).
382  *   - message: The human readable message to be displayed.
383  */
384 function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
385   foreach ($items as $delta => $item) {
386     if (!empty($item['value'])) {
387       if (!empty($field['settings']['max_length']) && drupal_strlen($item['value']) > $field['settings']['max_length']) {
388         $errors[$field['field_name']][$langcode][$delta][] = array(
389           'error' => 'text_max_length',
390           'message' => t('%name: the value may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length'])),
391         );
392       }
393     }
394   }
395 }
396
397 /**
398  * Define custom presave behavior for this module's field types.
399  *
400  * Make changes or additions to field values by altering the $items parameter by
401  * reference. There is no return value.
402  *
403  * @param $entity_type
404  *   The type of $entity.
405  * @param $entity
406  *   The entity for the operation.
407  * @param $field
408  *   The field structure for the operation.
409  * @param $instance
410  *   The instance structure for $field on $entity's bundle.
411  * @param $langcode
412  *   The language associated with $items.
413  * @param $items
414  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
415  */
416 function hook_field_presave($entity_type, $entity, $field, $instance, $langcode, &$items) {
417   if ($field['type'] == 'number_decimal') {
418     // Let PHP round the value to ensure consistent behavior across storage
419     // backends.
420     foreach ($items as $delta => $item) {
421       if (isset($item['value'])) {
422         $items[$delta]['value'] = round($item['value'], $field['settings']['scale']);
423       }
424     }
425   }
426 }
427
428 /**
429  * Define custom insert behavior for this module's field data.
430  *
431  * This hook is invoked from field_attach_insert() on the module that defines a
432  * field, during the process of inserting an entity object (node, taxonomy term,
433  * etc.). It is invoked just before the data for this field on the particular
434  * entity object is inserted into field storage. Only field modules that are
435  * storing or tracking information outside the standard field storage mechanism
436  * need to implement this hook.
437  *
438  * @param $entity_type
439  *   The type of $entity.
440  * @param $entity
441  *   The entity for the operation.
442  * @param $field
443  *   The field structure for the operation.
444  * @param $instance
445  *   The instance structure for $field on $entity's bundle.
446  * @param $langcode
447  *   The language associated with $items.
448  * @param $items
449  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
450  *
451  * @see hook_field_update()
452  * @see hook_field_delete()
453  */
454 function hook_field_insert($entity_type, $entity, $field, $instance, $langcode, &$items) {
455   if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node' && $entity->status) {
456     $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created', ));
457     foreach ($items as $item) {
458       $query->values(array(
459         'nid' => $entity->nid,
460         'tid' => $item['tid'],
461         'sticky' => $entity->sticky,
462         'created' => $entity->created,
463       ));
464     }
465     $query->execute();
466   }
467 }
468
469 /**
470  * Define custom update behavior for this module's field data.
471  *
472  * This hook is invoked from field_attach_update() on the module that defines a
473  * field, during the process of updating an entity object (node, taxonomy term,
474  * etc.). It is invoked just before the data for this field on the particular
475  * entity object is updated into field storage. Only field modules that are
476  * storing or tracking information outside the standard field storage mechanism
477  * need to implement this hook.
478  *
479  * @param $entity_type
480  *   The type of $entity.
481  * @param $entity
482  *   The entity for the operation.
483  * @param $field
484  *   The field structure for the operation.
485  * @param $instance
486  *   The instance structure for $field on $entity's bundle.
487  * @param $langcode
488  *   The language associated with $items.
489  * @param $items
490  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
491  *
492  * @see hook_field_insert()
493  * @see hook_field_delete()
494  */
495 function hook_field_update($entity_type, $entity, $field, $instance, $langcode, &$items) {
496   if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node') {
497     $first_call = &drupal_static(__FUNCTION__, array());
498
499     // We don't maintain data for old revisions, so clear all previous values
500     // from the table. Since this hook runs once per field, per object, make
501     // sure we only wipe values once.
502     if (!isset($first_call[$entity->nid])) {
503       $first_call[$entity->nid] = FALSE;
504       db_delete('taxonomy_index')->condition('nid', $entity->nid)->execute();
505     }
506     // Only save data to the table if the node is published.
507     if ($entity->status) {
508       $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created'));
509       foreach ($items as $item) {
510         $query->values(array(
511           'nid' => $entity->nid,
512           'tid' => $item['tid'],
513           'sticky' => $entity->sticky,
514           'created' => $entity->created,
515         ));
516       }
517       $query->execute();
518     }
519   }
520 }
521
522 /**
523  * Update the storage information for a field.
524  *
525  * This is invoked on the field's storage module from field_update_field(),
526  * before the new field information is saved to the database. The field storage
527  * module should update its storage tables to agree with the new field
528  * information. If there is a problem, the field storage module should throw an
529  * exception.
530  *
531  * @param $field
532  *   The updated field structure to be saved.
533  * @param $prior_field
534  *   The previously-saved field structure.
535  * @param $has_data
536  *   TRUE if the field has data in storage currently.
537  */
538 function hook_field_storage_update_field($field, $prior_field, $has_data) {
539   if (!$has_data) {
540     // There is no data. Re-create the tables completely.
541     $prior_schema = _field_sql_storage_schema($prior_field);
542     foreach ($prior_schema as $name => $table) {
543       db_drop_table($name, $table);
544     }
545     $schema = _field_sql_storage_schema($field);
546     foreach ($schema as $name => $table) {
547       db_create_table($name, $table);
548     }
549   }
550   else {
551     // There is data. See field_sql_storage_field_storage_update_field() for
552     // an example of what to do to modify the schema in place, preserving the
553     // old data as much as possible.
554   }
555   drupal_get_schema(NULL, TRUE);
556 }
557
558 /**
559  * Define custom delete behavior for this module's field data.
560  *
561  * This hook is invoked from field_attach_delete() on the module that defines a
562  * field, during the process of deleting an entity object (node, taxonomy term,
563  * etc.). It is invoked just before the data for this field on the particular
564  * entity object is deleted from field storage. Only field modules that are
565  * storing or tracking information outside the standard field storage mechanism
566  * need to implement this hook.
567  *
568  * @param $entity_type
569  *   The type of $entity.
570  * @param $entity
571  *   The entity for the operation.
572  * @param $field
573  *   The field structure for the operation.
574  * @param $instance
575  *   The instance structure for $field on $entity's bundle.
576  * @param $langcode
577  *   The language associated with $items.
578  * @param $items
579  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
580  *
581  * @see hook_field_insert()
582  * @see hook_field_update()
583  */
584 function hook_field_delete($entity_type, $entity, $field, $instance, $langcode, &$items) {
585   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
586   foreach ($items as $delta => $item) {
587     // For hook_file_references(), remember that this is being deleted.
588     $item['file_field_name'] = $field['field_name'];
589     // Pass in the ID of the object that is being removed so all references can
590     // be counted in hook_file_references().
591     $item['file_field_type'] = $entity_type;
592     $item['file_field_id'] = $id;
593     file_field_delete_file($item, $field, $entity_type, $id);
594   }
595 }
596
597 /**
598  * Define custom revision delete behavior for this module's field types.
599  *
600  * This hook is invoked just before the data is deleted from field storage
601  * in field_attach_delete_revision(), and will only be called for fieldable
602  * types that are versioned.
603  *
604  * @param $entity_type
605  *   The type of $entity.
606  * @param $entity
607  *   The entity for the operation.
608  * @param $field
609  *   The field structure for the operation.
610  * @param $instance
611  *   The instance structure for $field on $entity's bundle.
612  * @param $langcode
613  *   The language associated with $items.
614  * @param $items
615  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
616  */
617 function hook_field_delete_revision($entity_type, $entity, $field, $instance, $langcode, &$items) {
618   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
619   foreach ($items as $delta => $item) {
620     // For hook_file_references, remember that this file is being deleted.
621     $item['file_field_name'] = $field['field_name'];
622     if (file_field_delete_file($item, $field, $entity_type, $id)) {
623       $items[$delta] = NULL;
624     }
625   }
626 }
627
628 /**
629  * Define custom prepare_translation behavior for this module's field types.
630  *
631  * @param $entity_type
632  *   The type of $entity.
633  * @param $entity
634  *   The entity for the operation.
635  * @param $field
636  *   The field structure for the operation.
637  * @param $instance
638  *   The instance structure for $field on $entity's bundle.
639  * @param $langcode
640  *   The language associated to $items.
641  * @param $items
642  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
643  * @param $source_entity
644  *   The source entity from which field values are being copied.
645  * @param $source_langcode
646  *   The source language from which field values are being copied.
647  */
648 function hook_field_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) {
649   // If the translating user is not permitted to use the assigned text format,
650   // we must not expose the source values.
651   $field_name = $field['field_name'];
652   $formats = filter_formats();
653   $format_id = $source_entity->{$field_name}[$source_langcode][0]['format'];
654   if (!filter_access($formats[$format_id])) {
655     $items = array();
656   }
657 }
658
659 /**
660  * Define what constitutes an empty item for a field type.
661  *
662  * @param $item
663  *   An item that may or may not be empty.
664  * @param $field
665  *   The field to which $item belongs.
666  *
667  * @return
668  *   TRUE if $field's type considers $item not to contain any data;
669  *   FALSE otherwise.
670  */
671 function hook_field_is_empty($item, $field) {
672   if (empty($item['value']) && (string) $item['value'] !== '0') {
673     return TRUE;
674   }
675   return FALSE;
676 }
677
678 /**
679  * @} End of "defgroup field_types"
680  */
681
682 /**
683  * @defgroup field_widget Field Widget API
684  * @{
685  * Define Field API widget types.
686  *
687  * Field API widgets specify how fields are displayed in edit forms. Fields of a
688  * given @link field_types field type @endlink may be edited using more than one
689  * widget. In this case, the Field UI module allows the site builder to choose
690  * which widget to use. Widget types are defined by implementing
691  * hook_field_widget_info().
692  *
693  * Widgets are
694  * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API @endlink
695  * elements with additional processing capabilities. Widget hooks are typically
696  * called by the Field Attach API during the creation of the field form
697  * structure with field_attach_form().
698  *
699  * @see field
700  * @see field_types
701  * @see field_formatter
702  */
703
704 /**
705  * Expose Field API widget types.
706  *
707  * @return
708  *   An array describing the widget types implemented by the module.
709  *   The keys are widget type names. To avoid name clashes, widget type
710  *   names should be prefixed with the name of the module that exposes them.
711  *   The values are arrays describing the widget type, with the following
712  *   key/value pairs:
713  *   - label: The human-readable name of the widget type.
714  *   - description: A short description for the widget type.
715  *   - field types: An array of field types the widget supports.
716  *   - settings: An array whose keys are the names of the settings available
717  *     for the widget type, and whose values are the default values for those
718  *     settings.
719  *   - behaviors: (optional) An array describing behaviors of the widget, with
720  *     the following elements:
721  *     - multiple values: One of the following constants:
722  *       - FIELD_BEHAVIOR_DEFAULT: (default) If the widget allows the input of
723  *         one single field value (most common case). The widget will be
724  *         repeated for each value input.
725  *       - FIELD_BEHAVIOR_CUSTOM: If one single copy of the widget can receive
726  *         several field values. Examples: checkboxes, multiple select,
727  *         comma-separated textfield.
728  *     - default value: One of the following constants:
729  *       - FIELD_BEHAVIOR_DEFAULT: (default) If the widget accepts default
730  *         values.
731  *       - FIELD_BEHAVIOR_NONE: if the widget does not support default values.
732  *
733  * @see hook_field_widget_info_alter()
734  * @see hook_field_widget_form()
735  * @see hook_field_widget_form_alter()
736  * @see hook_field_widget_WIDGET_TYPE_form_alter()
737  * @see hook_field_widget_error()
738  * @see hook_field_widget_settings_form()
739  */
740 function hook_field_widget_info() {
741     return array(
742     'text_textfield' => array(
743       'label' => t('Text field'),
744       'field types' => array('text'),
745       'settings' => array('size' => 60),
746       'behaviors' => array(
747         'multiple values' => FIELD_BEHAVIOR_DEFAULT,
748         'default value' => FIELD_BEHAVIOR_DEFAULT,
749       ),
750     ),
751     'text_textarea' => array(
752       'label' => t('Text area (multiple rows)'),
753       'field types' => array('text_long'),
754       'settings' => array('rows' => 5),
755       'behaviors' => array(
756         'multiple values' => FIELD_BEHAVIOR_DEFAULT,
757         'default value' => FIELD_BEHAVIOR_DEFAULT,
758       ),
759     ),
760     'text_textarea_with_summary' => array(
761       'label' => t('Text area with a summary'),
762       'field types' => array('text_with_summary'),
763       'settings' => array('rows' => 20, 'summary_rows' => 5),
764       'behaviors' => array(
765         'multiple values' => FIELD_BEHAVIOR_DEFAULT,
766         'default value' => FIELD_BEHAVIOR_DEFAULT,
767       ),
768     ),
769   );
770 }
771
772 /**
773  * Perform alterations on Field API widget types.
774  *
775  * @param $info
776  *   Array of informations on widget types exposed by hook_field_widget_info()
777  *   implementations.
778  */
779 function hook_field_widget_info_alter(&$info) {
780   // Add a setting to a widget type.
781   $info['text_textfield']['settings'] += array(
782     'mymodule_additional_setting' => 'default value',
783   );
784
785   // Let a new field type re-use an existing widget.
786   $info['options_select']['field types'][] = 'my_field_type';
787 }
788
789 /**
790  * Return the form for a single field widget.
791  *
792  * Field widget form elements should be based on the passed-in $element, which
793  * contains the base form element properties derived from the field
794  * configuration.
795  *
796  * Field API will set the weight, field name and delta values for each form
797  * element. If there are multiple values for this field, the Field API will
798  * invoke this hook as many times as needed.
799  *
800  * Note that, depending on the context in which the widget is being included
801  * (regular entity form, field configuration form, advanced search form...),
802  * the values for $field and $instance might be different from the "official"
803  * definitions returned by field_info_field() and field_info_instance().
804  * Examples: mono-value widget even if the field is multi-valued, non-required
805  * widget even if the field is 'required'...
806  *
807  * Therefore, the FAPI element callbacks (such as #process, #element_validate,
808  * #value_callback...) used by the widget cannot use the field_info_field()
809  * or field_info_instance() functions to retrieve the $field or $instance
810  * definitions they should operate on. The field_widget_field() and
811  * field_widget_instance() functions should be used instead to fetch the
812  * current working definitions from $form_state, where Field API stores them.
813  *
814  * Alternatively, hook_field_widget_form() can extract the needed specific
815  * properties from $field and $instance and set them as ad-hoc
816  * $element['#custom'] properties, for later use by its element callbacks.
817  *
818  * Other modules may alter the form element provided by this function using
819  * hook_field_widget_form_alter().
820  *
821  * @param $form
822  *   The form structure where widgets are being attached to. This might be a
823  *   full form structure, or a sub-element of a larger form.
824  * @param $form_state
825  *   An associative array containing the current state of the form.
826  * @param $field
827  *   The field structure.
828  * @param $instance
829  *   The field instance.
830  * @param $langcode
831  *   The language associated with $items.
832  * @param $items
833  *   Array of default values for this field.
834  * @param $delta
835  *   The order of this item in the array of subelements (0, 1, 2, etc).
836  * @param $element
837  *   A form element array containing basic properties for the widget:
838  *   - #entity_type: The name of the entity the field is attached to.
839  *   - #bundle: The name of the field bundle the field is contained in.
840  *   - #field_name: The name of the field.
841  *   - #language: The language the field is being edited in.
842  *   - #field_parents: The 'parents' space for the field in the form. Most
843  *       widgets can simply overlook this property. This identifies the
844  *       location where the field values are placed within
845  *       $form_state['values'], and is used to access processing information
846  *       for the field through the field_form_get_state() and
847  *       field_form_set_state() functions.
848  *   - #columns: A list of field storage columns of the field.
849  *   - #title: The sanitized element label for the field instance, ready for
850  *     output.
851  *   - #description: The sanitized element description for the field instance,
852  *     ready for output.
853  *   - #required: A Boolean indicating whether the element value is required;
854  *     for required multiple value fields, only the first widget's values are
855  *     required.
856  *   - #delta: The order of this item in the array of subelements; see $delta
857  *     above.
858  *
859  * @return
860  *   The form elements for a single widget for this field.
861  *
862  * @see field_widget_field()
863  * @see field_widget_instance()
864  * @see hook_field_widget_form_alter()
865  * @see hook_field_widget_WIDGET_TYPE_form_alter()
866  */
867 function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
868   $element += array(
869     '#type' => $instance['widget']['type'],
870     '#default_value' => isset($items[$delta]) ? $items[$delta] : '',
871   );
872   return $element;
873 }
874
875 /**
876  * Alter forms for field widgets provided by other modules.
877  *
878  * @param $element
879  *   The field widget form element as constructed by hook_field_widget_form().
880  * @param $form_state
881  *   An associative array containing the current state of the form.
882  * @param $context
883  *   An associative array containing the following key-value pairs, matching the
884  *   arguments received by hook_field_widget_form():
885  *   - form: The form structure to which widgets are being attached. This may be
886  *     a full form structure, or a sub-element of a larger form.
887  *   - field: The field structure.
888  *   - instance: The field instance structure.
889  *   - langcode: The language associated with $items.
890  *   - items: Array of default values for this field.
891  *   - delta: The order of this item in the array of subelements (0, 1, 2, etc).
892  *
893  * @see hook_field_widget_form()
894  * @see hook_field_widget_WIDGET_TYPE_form_alter()
895  */
896 function hook_field_widget_form_alter(&$element, &$form_state, $context) {
897   // Add a css class to widget form elements for all fields of type mytype.
898   if ($context['field']['type'] == 'mytype') {
899     // Be sure not to overwrite existing attributes.
900     $element['#attributes']['class'][] = 'myclass';
901   }
902 }
903
904 /**
905  * Alter widget forms for a specific widget provided by another module.
906  *
907  * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
908  * specific widget form, rather than using hook_field_widget_form_alter() and
909  * checking the widget type.
910  *
911  * @param $element
912  *   The field widget form element as constructed by hook_field_widget_form().
913  * @param $form_state
914  *   An associative array containing the current state of the form.
915  * @param $context
916  *   An associative array containing the following key-value pairs, matching the
917  *   arguments received by hook_field_widget_form():
918  *   - "form": The form structure where widgets are being attached to. This
919  *     might be a full form structure, or a sub-element of a larger form.
920  *   - "field": The field structure.
921  *   - "instance": The field instance structure.
922  *   - "langcode": The language associated with $items.
923  *   - "items": Array of default values for this field.
924  *   - "delta": The order of this item in the array of subelements (0, 1, 2,
925  *     etc).
926  *
927  * @see hook_field_widget_form()
928  * @see hook_field_widget_form_alter()
929  */
930 function hook_field_widget_WIDGET_TYPE_form_alter(&$element, &$form_state, $context) {
931   // Code here will only act on widgets of type WIDGET_TYPE.  For example,
932   // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
933   // widgets of type 'mymodule_autocomplete'.
934   $element['#autocomplete_path'] = 'mymodule/autocomplete_path';
935 }
936
937 /**
938  * Flag a field-level validation error.
939  *
940  * @param $element
941  *   An array containing the form element for the widget. The error needs to be
942  *   flagged on the right sub-element, according to the widget's internal
943  *   structure.
944  * @param $error
945  *   An associative array with the following key-value pairs, as returned by
946  *   hook_field_validate():
947  *   - error: the error code. Complex widgets might need to report different
948  *     errors to different form elements inside the widget.
949  *   - message: the human readable message to be displayed.
950  * @param $form
951  *   The form structure where field elements are attached to. This might be a
952  *   full form structure, or a sub-element of a larger form.
953  * @param $form_state
954  *   An associative array containing the current state of the form.
955  */
956 function hook_field_widget_error($element, $error, $form, &$form_state) {
957   form_error($element['value'], $error['message']);
958 }
959
960
961 /**
962  * @} End of "defgroup field_widget"
963  */
964
965
966 /**
967  * @defgroup field_formatter Field Formatter API
968  * @{
969  * Define Field API formatter types.
970  *
971  * Field API formatters specify how fields are displayed when the entity to
972  * which the field is attached is displayed. Fields of a given
973  * @link field_types field type @endlink may be displayed using more than one
974  * formatter. In this case, the Field UI module allows the site builder to
975  * choose which formatter to use. Field formatters are defined by implementing
976  * hook_field_formatter_info().
977  *
978  * @see field
979  * @see field_types
980  * @see field_widget
981  */
982
983 /**
984  * Expose Field API formatter types.
985  *
986  * Formatters handle the display of field values. Formatter hooks are typically
987  * called by the Field Attach API field_attach_prepare_view() and
988  * field_attach_view() functions.
989  *
990  * @return
991  *   An array describing the formatter types implemented by the module.
992  *   The keys are formatter type names. To avoid name clashes, formatter type
993  *   names should be prefixed with the name of the module that exposes them.
994  *   The values are arrays describing the formatter type, with the following
995  *   key/value pairs:
996  *   - label: The human-readable name of the formatter type.
997  *   - description: A short description for the formatter type.
998  *   - field types: An array of field types the formatter supports.
999  *   - settings: An array whose keys are the names of the settings available
1000  *     for the formatter type, and whose values are the default values for
1001  *     those settings.
1002  *
1003  * @see hook_field_formatter_info_alter()
1004  * @see hook_field_formatter_view()
1005  * @see hook_field_formatter_prepare_view()
1006  */
1007 function hook_field_formatter_info() {
1008   return array(
1009     'text_default' => array(
1010       'label' => t('Default'),
1011       'field types' => array('text', 'text_long', 'text_with_summary'),
1012     ),
1013     'text_plain' => array(
1014       'label' => t('Plain text'),
1015       'field types' => array('text', 'text_long', 'text_with_summary'),
1016     ),
1017
1018     // The text_trimmed formatter displays the trimmed version of the
1019     // full element of the field. It is intended to be used with text
1020     // and text_long fields. It also works with text_with_summary
1021     // fields though the text_summary_or_trimmed formatter makes more
1022     // sense for that field type.
1023     'text_trimmed' => array(
1024       'label' => t('Trimmed'),
1025       'field types' => array('text', 'text_long', 'text_with_summary'),
1026     ),
1027
1028     // The 'summary or trimmed' field formatter for text_with_summary
1029     // fields displays returns the summary element of the field or, if
1030     // the summary is empty, the trimmed version of the full element
1031     // of the field.
1032     'text_summary_or_trimmed' => array(
1033       'label' => t('Summary or trimmed'),
1034       'field types' => array('text_with_summary'),
1035     ),
1036   );
1037 }
1038
1039 /**
1040  * Perform alterations on Field API formatter types.
1041  *
1042  * @param $info
1043  *   Array of informations on formatter types exposed by
1044  *   hook_field_field_formatter_info() implementations.
1045  */
1046 function hook_field_formatter_info_alter(&$info) {
1047   // Add a setting to a formatter type.
1048   $info['text_default']['settings'] += array(
1049     'mymodule_additional_setting' => 'default value',
1050   );
1051
1052   // Let a new field type re-use an existing formatter.
1053   $info['text_default']['field types'][] = 'my_field_type';
1054 }
1055
1056 /**
1057  * Allow formatters to load information for field values being displayed.
1058  *
1059  * This should be used when a formatter needs to load additional information
1060  * from the database in order to render a field, for example a reference field
1061  * which displays properties of the referenced entities such as name or type.
1062  *
1063  * This hook is called after the field type's own hook_field_prepare_view().
1064  *
1065  * Unlike most other field hooks, this hook operates on multiple entities. The
1066  * $entities, $instances and $items parameters are arrays keyed by entity ID.
1067  * For performance reasons, information for all available entities should be
1068  * loaded in a single query where possible.
1069  *
1070  * @param $entity_type
1071  *   The type of $entity.
1072  * @param $entities
1073  *   Array of entities being displayed, keyed by entity ID.
1074  * @param $field
1075  *   The field structure for the operation.
1076  * @param $instances
1077  *   Array of instance structures for $field for each entity, keyed by entity
1078  *   ID.
1079  * @param $langcode
1080  *   The language the field values are to be shown in. If no language is
1081  *   provided the current language is used.
1082  * @param $items
1083  *   Array of field values for the entities, keyed by entity ID.
1084  * @param $displays
1085  *   Array of display settings to use for each entity, keyed by entity ID.
1086  *
1087  * @return
1088  *   Changes or additions to field values are done by altering the $items
1089  *   parameter by reference.
1090  */
1091 function hook_field_formatter_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $displays) {
1092   $tids = array();
1093
1094   // Collect every possible term attached to any of the fieldable entities.
1095   foreach ($entities as $id => $entity) {
1096     foreach ($items[$id] as $delta => $item) {
1097       // Force the array key to prevent duplicates.
1098       $tids[$item['tid']] = $item['tid'];
1099     }
1100   }
1101
1102   if ($tids) {
1103     $terms = taxonomy_term_load_multiple($tids);
1104
1105     // Iterate through the fieldable entities again to attach the loaded term
1106     // data.
1107     foreach ($entities as $id => $entity) {
1108       $rekey = FALSE;
1109
1110       foreach ($items[$id] as $delta => $item) {
1111         // Check whether the taxonomy term field instance value could be loaded.
1112         if (isset($terms[$item['tid']])) {
1113           // Replace the instance value with the term data.
1114           $items[$id][$delta]['taxonomy_term'] = $terms[$item['tid']];
1115         }
1116         // Otherwise, unset the instance value, since the term does not exist.
1117         else {
1118           unset($items[$id][$delta]);
1119           $rekey = TRUE;
1120         }
1121       }
1122
1123       if ($rekey) {
1124         // Rekey the items array.
1125         $items[$id] = array_values($items[$id]);
1126       }
1127     }
1128   }
1129 }
1130
1131 /**
1132  * Build a renderable array for a field value.
1133  *
1134  * @param $entity_type
1135  *   The type of $entity.
1136  * @param $entity
1137  *   The entity being displayed.
1138  * @param $field
1139  *   The field structure.
1140  * @param $instance
1141  *   The field instance.
1142  * @param $langcode
1143  *   The language associated with $items.
1144  * @param $items
1145  *   Array of values for this field.
1146  * @param $display
1147  *   The display settings to use, as found in the 'display' entry of instance
1148  *   definitions. The array notably contains the following keys and values;
1149  *   - type: The name of the formatter to use.
1150  *   - settings: The array of formatter settings.
1151  *
1152  * @return
1153  *   A renderable array for the $items, as an array of child elements keyed
1154  *   by numeric indexes starting from 0.
1155  */
1156 function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
1157   $element = array();
1158   $settings = $display['settings'];
1159
1160   switch ($display['type']) {
1161     case 'sample_field_formatter_simple':
1162       // Common case: each value is displayed individually in a sub-element
1163       // keyed by delta. The field.tpl.php template specifies the markup
1164       // wrapping each value.
1165       foreach ($items as $delta => $item) {
1166         $element[$delta] = array('#markup' => $settings['some_setting'] . $item['value']);
1167       }
1168       break;
1169
1170     case 'sample_field_formatter_themeable':
1171       // More elaborate formatters can defer to a theme function for easier
1172       // customization.
1173       foreach ($items as $delta => $item) {
1174         $element[$delta] = array(
1175           '#theme' => 'mymodule_theme_sample_field_formatter_themeable',
1176           '#data' => $item['value'],
1177           '#some_setting' => $settings['some_setting'],
1178         );
1179       }
1180       break;
1181
1182     case 'sample_field_formatter_combined':
1183       // Some formatters might need to display all values within a single piece
1184       // of markup.
1185       $rows = array();
1186       foreach ($items as $delta => $item) {
1187         $rows[] = array($delta, $item['value']);
1188       }
1189       $element[0] = array(
1190         '#theme' => 'table',
1191         '#header' => array(t('Delta'), t('Value')),
1192         '#rows' => $rows,
1193       );
1194       break;
1195   }
1196
1197   return $element;
1198 }
1199
1200 /**
1201  * @} End of "defgroup field_formatter"
1202  */
1203
1204 /**
1205  * @ingroup field_attach
1206  * @{
1207  */
1208
1209 /**
1210  * Act on field_attach_form().
1211  *
1212  * This hook is invoked after the field module has performed the operation.
1213  * Implementing modules should alter the $form or $form_state parameters.
1214  *
1215  * @param $entity_type
1216  *   The type of $entity; for example, 'node' or 'user'.
1217  * @param $entity
1218  *   The entity for which an edit form is being built.
1219  * @param $form
1220  *   The form structure where field elements are attached to. This might be a
1221  *   full form structure, or a sub-element of a larger form. The
1222  *   $form['#parents'] property can be used to identify the corresponding part
1223  *   of $form_state['values']. Hook implementations that need to act on the
1224  *   top-level properties of the global form (like #submit, #validate...) can
1225  *   add a #process callback to the array received in the $form parameter, and
1226  *   act on the $complete_form parameter in the process callback.
1227  * @param $form_state
1228  *   An associative array containing the current state of the form.
1229  * @param $langcode
1230  *   The language the field values are going to be entered in. If no language
1231  *   is provided the default site language will be used.
1232  */
1233 function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) {
1234   // Add a checkbox allowing a given field to be emptied.
1235   // See hook_field_attach_submit() for the corresponding processing code.
1236   $form['empty_field_foo'] = array(
1237     '#type' => 'checkbox',
1238     '#title' => t("Empty the 'field_foo' field"),
1239   );
1240 }
1241
1242 /**
1243  * Act on field_attach_load().
1244  *
1245  * This hook is invoked after the field module has performed the operation.
1246  *
1247  * Unlike other field_attach hooks, this hook accounts for 'multiple loads'.
1248  * Instead of the usual $entity parameter, it accepts an array of entities,
1249  * indexed by entity ID. For performance reasons, information for all available
1250  * entities should be loaded in a single query where possible.
1251  *
1252  * The changes made to the entities' field values get cached by the field cache
1253  * for subsequent loads.
1254  *
1255  * See field_attach_load() for details and arguments.
1256  */
1257 function hook_field_attach_load($entity_type, $entities, $age, $options) {
1258   // @todo Needs function body.
1259 }
1260
1261 /**
1262  * Act on field_attach_validate().
1263  *
1264  * This hook is invoked after the field module has performed the operation.
1265  *
1266  * See field_attach_validate() for details and arguments.
1267  */
1268 function hook_field_attach_validate($entity_type, $entity, &$errors) {
1269   // @todo Needs function body.
1270 }
1271
1272 /**
1273  * Act on field_attach_submit().
1274  *
1275  * This hook is invoked after the field module has performed the operation.
1276  *
1277  * @param $entity_type
1278  *   The type of $entity; for example, 'node' or 'user'.
1279  * @param $entity
1280  *   The entity for which an edit form is being submitted. The incoming form
1281  *   values have been extracted as field values of the $entity object.
1282  * @param $form
1283  *   The form structure where field elements are attached to. This might be a
1284  *   full form structure, or a sub-part of a larger form. The $form['#parents']
1285  *   property can be used to identify the corresponding part of
1286  *   $form_state['values'].
1287  * @param $form_state
1288  *   An associative array containing the current state of the form.
1289  */
1290 function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
1291   // Sample case of an 'Empty the field' checkbox added on the form, allowing
1292   // a given field to be emptied.
1293   $values = drupal_array_get_nested_value($form_state['values'], $form['#parents']);
1294   if (!empty($values['empty_field_foo'])) {
1295     unset($entity->field_foo);
1296   }
1297 }
1298
1299 /**
1300  * Act on field_attach_presave().
1301  *
1302  * This hook is invoked after the field module has performed the operation.
1303  *
1304  * See field_attach_presave() for details and arguments.
1305  */
1306 function hook_field_attach_presave($entity_type, $entity) {
1307   // @todo Needs function body.
1308 }
1309
1310 /**
1311  * Act on field_attach_insert().
1312  *
1313  * This hook is invoked after the field module has performed the operation.
1314  *
1315  * See field_attach_insert() for details and arguments.
1316  */
1317 function hook_field_attach_insert($entity_type, $entity) {
1318   // @todo Needs function body.
1319 }
1320
1321 /**
1322  * Act on field_attach_update().
1323  *
1324  * This hook is invoked after the field module has performed the operation.
1325  *
1326  * See field_attach_update() for details and arguments.
1327  */
1328 function hook_field_attach_update($entity_type, $entity) {
1329   // @todo Needs function body.
1330 }
1331
1332 /**
1333  * Alter field_attach_preprocess() variables.
1334  *
1335  * This hook is invoked while preprocessing the field.tpl.php template file
1336  * in field_attach_preprocess().
1337  *
1338  * @param $variables
1339  *   The variables array is passed by reference and will be populated with field
1340  *   values.
1341  * @param $context
1342  *   An associative array containing:
1343  *   - entity_type: The type of $entity; for example, 'node' or 'user'.
1344  *   - entity: The entity with fields to render.
1345  *   - element: The structured array containing the values ready for rendering.
1346  */
1347 function hook_field_attach_preprocess_alter(&$variables, $context) {
1348   // @todo Needs function body.
1349 }
1350
1351 /**
1352  * Act on field_attach_delete().
1353  *
1354  * This hook is invoked after the field module has performed the operation.
1355  *
1356  * See field_attach_delete() for details and arguments.
1357  */
1358 function hook_field_attach_delete($entity_type, $entity) {
1359   // @todo Needs function body.
1360 }
1361
1362 /**
1363  * Act on field_attach_delete_revision().
1364  *
1365  * This hook is invoked after the field module has performed the operation.
1366  *
1367  * See field_attach_delete_revision() for details and arguments.
1368  */
1369 function hook_field_attach_delete_revision($entity_type, $entity) {
1370   // @todo Needs function body.
1371 }
1372
1373 /**
1374  * Act on field_purge_data().
1375  *
1376  * This hook is invoked in field_purge_data() and allows modules to act on
1377  * purging data from a single field pseudo-entity. For example, if a module
1378  * relates data in the field with its own data, it may purge its own data
1379  * during this process as well.
1380  *
1381  * @param $entity_type
1382  *   The type of $entity; for example, 'node' or 'user'.
1383  * @param $entity
1384  *   The pseudo-entity whose field data is being purged.
1385  * @param $field
1386  *   The (possibly deleted) field whose data is being purged.
1387  * @param $instance
1388  *   The deleted field instance whose data is being purged.
1389  *
1390  * @see @link field_purge Field API bulk data deletion @endlink
1391  * @see field_purge_data()
1392  */
1393 function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
1394   // find the corresponding data in mymodule and purge it
1395   if ($entity_type == 'node' && $field->field_name == 'my_field_name') {
1396     mymodule_remove_mydata($entity->nid);
1397   }
1398 }
1399
1400 /**
1401  * Perform alterations on field_attach_view() or field_view_field().
1402  *
1403  * This hook is invoked after the field module has performed the operation.
1404  *
1405  * @param $output
1406  *   The structured content array tree for all of the entity's fields.
1407  * @param $context
1408  *   An associative array containing:
1409  *   - entity_type: The type of $entity; for example, 'node' or 'user'.
1410  *   - entity: The entity with fields to render.
1411  *   - view_mode: View mode; for example, 'full' or 'teaser'.
1412  *   - display: Either a view mode string or an array of display settings. If
1413  *     this hook is being invoked from field_attach_view(), the 'display'
1414  *     element is set to the view mode string. If this hook is being invoked
1415  *     from field_view_field(), this element is set to the $display argument
1416  *     and the view_mode element is set to '_custom'. See field_view_field()
1417  *     for more information on what its $display argument contains.
1418  *   - language: The language code used for rendering.
1419  */
1420 function hook_field_attach_view_alter(&$output, $context) {
1421   // Append RDF term mappings on displayed taxonomy links.
1422   foreach (element_children($output) as $field_name) {
1423     $element = &$output[$field_name];
1424     if ($element['#field_type'] == 'taxonomy_term_reference' && $element['#formatter'] == 'taxonomy_term_reference_link') {
1425       foreach ($element['#items'] as $delta => $item) {
1426         $term = $item['taxonomy_term'];
1427         if (!empty($term->rdf_mapping['rdftype'])) {
1428           $element[$delta]['#options']['attributes']['typeof'] = $term->rdf_mapping['rdftype'];
1429         }
1430         if (!empty($term->rdf_mapping['name']['predicates'])) {
1431           $element[$delta]['#options']['attributes']['property'] = $term->rdf_mapping['name']['predicates'];
1432         }
1433       }
1434     }
1435   }
1436 }
1437
1438 /**
1439  * Perform alterations on field_attach_prepare_translation().
1440  *
1441  * This hook is invoked after the field module has performed the operation.
1442  *
1443  * @param $entity
1444  *   The entity being prepared for translation.
1445  * @param $context
1446  *   An associative array containing:
1447  *   - entity_type: The type of $entity; e.g. 'node' or 'user'.
1448  *   - langcode: The language the entity has to be translated in.
1449  *   - source_entity: The entity holding the field values to be translated.
1450  *   - source_langcode: The source language from which translate.
1451  */
1452 function hook_field_attach_prepare_translation_alter(&$entity, $context) {
1453   if ($context['entity_type'] == 'custom_entity_type') {
1454     $entity->custom_field = $context['source_entity']->custom_field;
1455   }
1456 }
1457
1458 /**
1459  * Perform alterations on field_language() values.
1460  *
1461  * This hook is invoked to alter the array of display languages for the given
1462  * entity.
1463  *
1464  * @param $display_language
1465  *   A reference to an array of language codes keyed by field name.
1466  * @param $context
1467  *   An associative array containing:
1468  *   - entity_type: The type of the entity to be displayed.
1469  *   - entity: The entity with fields to render.
1470  *   - langcode: The language code $entity has to be displayed in.
1471  */
1472 function hook_field_language_alter(&$display_language, $context) {
1473   // Do not apply core language fallback rules if they are disabled or if Locale
1474   // is not registered as a translation handler.
1475   if (variable_get('locale_field_language_fallback', TRUE) && field_has_translation_handler($context['entity_type'], 'locale')) {
1476     locale_field_language_fallback($display_language, $context['entity'], $context['language']);
1477   }
1478 }
1479
1480 /**
1481  * Alter field_available_languages() values.
1482  *
1483  * This hook is invoked from field_available_languages() to allow modules to
1484  * alter the array of available languages for the given field.
1485  *
1486  * @param $languages
1487  *   A reference to an array of language codes to be made available.
1488  * @param $context
1489  *   An associative array containing:
1490  *   - entity_type: The type of the entity the field is attached to.
1491  *   - field: A field data structure.
1492  */
1493 function hook_field_available_languages_alter(&$languages, $context) {
1494   // Add an unavailable language.
1495   $languages[] = 'xx';
1496
1497   // Remove an available language.
1498   $index = array_search('yy', $languages);
1499   unset($languages[$index]);
1500 }
1501
1502 /**
1503  * Act on field_attach_create_bundle().
1504  *
1505  * This hook is invoked after the field module has performed the operation.
1506  *
1507  * See field_attach_create_bundle() for details and arguments.
1508  */
1509 function hook_field_attach_create_bundle($entity_type, $bundle) {
1510   // When a new bundle is created, the menu needs to be rebuilt to add the
1511   // Field UI menu item tabs.
1512   variable_set('menu_rebuild_needed', TRUE);
1513 }
1514
1515 /**
1516  * Act on field_attach_rename_bundle().
1517  *
1518  * This hook is invoked after the field module has performed the operation.
1519  *
1520  * See field_attach_rename_bundle() for details and arguments.
1521  */
1522 function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
1523   // Update the extra weights variable with new information.
1524   if ($bundle_old !== $bundle_new) {
1525     $extra_weights = variable_get('field_extra_weights', array());
1526     if (isset($info[$entity_type][$bundle_old])) {
1527       $extra_weights[$entity_type][$bundle_new] = $extra_weights[$entity_type][$bundle_old];
1528       unset($extra_weights[$entity_type][$bundle_old]);
1529       variable_set('field_extra_weights', $extra_weights);
1530     }
1531   }
1532 }
1533
1534 /**
1535  * Act on field_attach_delete_bundle.
1536  *
1537  * This hook is invoked after the field module has performed the operation.
1538  *
1539  * @param $entity_type
1540  *   The type of entity; for example, 'node' or 'user'.
1541  * @param $bundle
1542  *   The bundle that was just deleted.
1543  * @param $instances
1544  *   An array of all instances that existed for the bundle before it was
1545  *   deleted.
1546  */
1547 function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) {
1548   // Remove the extra weights variable information for this bundle.
1549   $extra_weights = variable_get('field_extra_weights', array());
1550   if (isset($extra_weights[$entity_type][$bundle])) {
1551     unset($extra_weights[$entity_type][$bundle]);
1552     variable_set('field_extra_weights', $extra_weights);
1553   }
1554 }
1555
1556 /**
1557  * @} End of "defgroup field_attach"
1558  */
1559
1560 /**
1561  * @ingroup field_storage
1562  * @{
1563  */
1564
1565 /**
1566  * Expose Field API storage backends.
1567  *
1568  * @return
1569  *   An array describing the storage backends implemented by the module.
1570  *   The keys are storage backend names. To avoid name clashes, storage backend
1571  *   names should be prefixed with the name of the module that exposes them.
1572  *   The values are arrays describing the storage backend, with the following
1573  *   key/value pairs:
1574  *   - label: The human-readable name of the storage backend.
1575  *   - description: A short description for the storage backend.
1576  *   - settings: An array whose keys are the names of the settings available
1577  *     for the storage backend, and whose values are the default values for
1578  *     those settings.
1579  */
1580 function hook_field_storage_info() {
1581   return array(
1582     'field_sql_storage' => array(
1583       'label' => t('Default SQL storage'),
1584       'description' => t('Stores fields in the local SQL database, using per-field tables.'),
1585       'settings' => array(),
1586     ),
1587   );
1588 }
1589
1590 /**
1591  * Perform alterations on Field API storage types.
1592  *
1593  * @param $info
1594  *   Array of informations on storage types exposed by
1595  *   hook_field_field_storage_info() implementations.
1596  */
1597 function hook_field_storage_info_alter(&$info) {
1598   // Add a setting to a storage type.
1599   $info['field_sql_storage']['settings'] += array(
1600     'mymodule_additional_setting' => 'default value',
1601   );
1602 }
1603
1604 /**
1605  * Reveal the internal details about the storage for a field.
1606  *
1607  * For example, an SQL storage module might return the Schema API structure for
1608  * the table. A key/value storage module might return the server name,
1609  * authentication credentials, and bin name.
1610  *
1611  * Field storage modules are not obligated to implement this hook. Modules
1612  * that rely on these details must only use them for read operations.
1613  *
1614  * @param $field
1615  *   A field structure.
1616  *
1617  * @return
1618  *   An array of details.
1619  *    - The first dimension is a store type (sql, solr, etc).
1620  *    - The second dimension indicates the age of the values in the store
1621  *      FIELD_LOAD_CURRENT or FIELD_LOAD_REVISION.
1622  *    - Other dimensions are specific to the field storage module.
1623  *
1624  * @see hook_field_storage_details_alter()
1625  */
1626 function hook_field_storage_details($field) {
1627   $details = array();
1628
1629   // Add field columns.
1630   foreach ((array) $field['columns'] as $column_name => $attributes) {
1631     $real_name = _field_sql_storage_columnname($field['field_name'], $column_name);
1632     $columns[$column_name] = $real_name;
1633   }
1634   return array(
1635     'sql' => array(
1636       FIELD_LOAD_CURRENT => array(
1637         _field_sql_storage_tablename($field) => $columns,
1638       ),
1639       FIELD_LOAD_REVISION => array(
1640         _field_sql_storage_revision_tablename($field) => $columns,
1641       ),
1642     ),
1643   );
1644 }
1645
1646 /**
1647  * Perform alterations on Field API storage details.
1648  *
1649  * @param $details
1650  *   An array of storage details for fields as exposed by
1651  *   hook_field_storage_details() implementations.
1652  * @param $field
1653  *   A field structure.
1654  *
1655  * @see hook_field_storage_details()
1656  */
1657 function hook_field_storage_details_alter(&$details, $field) {
1658   if ($field['field_name'] == 'field_of_interest') {
1659     $columns = array();
1660     foreach ((array) $field['columns'] as $column_name => $attributes) {
1661       $columns[$column_name] = $column_name;
1662     }
1663     $details['drupal_variables'] = array(
1664       FIELD_LOAD_CURRENT => array(
1665         'moon' => $columns,
1666       ),
1667       FIELD_LOAD_REVISION => array(
1668         'mars' => $columns,
1669       ),
1670     );
1671   }
1672 }
1673
1674 /**
1675  * Load field data for a set of entities.
1676  *
1677  * This hook is invoked from field_attach_load() to ask the field storage
1678  * module to load field data.
1679  *
1680  * Modules implementing this hook should load field values and add them to
1681  * objects in $entities. Fields with no values should be added as empty
1682  * arrays.
1683  *
1684  * @param $entity_type
1685  *   The type of entity, such as 'node' or 'user'.
1686  * @param $entities
1687  *   The array of entity objects to add fields to, keyed by entity ID.
1688  * @param $age
1689  *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
1690  *   FIELD_LOAD_REVISION to load the version indicated by each entity.
1691  * @param $fields
1692  *   An array listing the fields to be loaded. The keys of the array are field
1693  *   IDs, and the values of the array are the entity IDs (or revision IDs,
1694  *   depending on the $age parameter) to add each field to.
1695  * @param $options
1696  *   An associative array of additional options, with the following keys:
1697  *   - deleted: If TRUE, deleted fields should be loaded as well as
1698  *     non-deleted fields. If unset or FALSE, only non-deleted fields should be
1699  *     loaded.
1700  */
1701 function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) {
1702   $field_info = field_info_field_by_ids();
1703   $load_current = $age == FIELD_LOAD_CURRENT;
1704
1705   foreach ($fields as $field_id => $ids) {
1706     $field = $field_info[$field_id];
1707     $field_name = $field['field_name'];
1708     $table = $load_current ? _field_sql_storage_tablename($field) : _field_sql_storage_revision_tablename($field);
1709
1710     $query = db_select($table, 't')
1711       ->fields('t')
1712       ->condition('entity_type', $entity_type)
1713       ->condition($load_current ? 'entity_id' : 'revision_id', $ids, 'IN')
1714       ->condition('language', field_available_languages($entity_type, $field), 'IN')
1715       ->orderBy('delta');
1716
1717     if (empty($options['deleted'])) {
1718       $query->condition('deleted', 0);
1719     }
1720
1721     $results = $query->execute();
1722
1723     $delta_count = array();
1724     foreach ($results as $row) {
1725       if (!isset($delta_count[$row->entity_id][$row->language])) {
1726         $delta_count[$row->entity_id][$row->language] = 0;
1727       }
1728
1729       if ($field['cardinality'] == FIELD_CARDINALITY_UNLIMITED || $delta_count[$row->entity_id][$row->language] < $field['cardinality']) {
1730         $item = array();
1731         // For each column declared by the field, populate the item
1732         // from the prefixed database column.
1733         foreach ($field['columns'] as $column => $attributes) {
1734           $column_name = _field_sql_storage_columnname($field_name, $column);
1735           $item[$column] = $row->$column_name;
1736         }
1737
1738         // Add the item to the field values for the entity.
1739         $entities[$row->entity_id]->{$field_name}[$row->language][] = $item;
1740         $delta_count[$row->entity_id][$row->language]++;
1741       }
1742     }
1743   }
1744 }
1745
1746 /**
1747  * Write field data for an entity.
1748  *
1749  * This hook is invoked from field_attach_insert() and field_attach_update(),
1750  * to ask the field storage module to save field data.
1751  *
1752  * @param $entity_type
1753  *   The entity type of entity, such as 'node' or 'user'.
1754  * @param $entity
1755  *   The entity on which to operate.
1756  * @param $op
1757  *   FIELD_STORAGE_UPDATE when updating an existing entity,
1758  *   FIELD_STORAGE_INSERT when inserting a new entity.
1759  * @param $fields
1760  *   An array listing the fields to be written. The keys and values of the
1761  *   array are field IDs.
1762  */
1763 function hook_field_storage_write($entity_type, $entity, $op, $fields) {
1764   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
1765   if (!isset($vid)) {
1766     $vid = $id;
1767   }
1768
1769   foreach ($fields as $field_id) {
1770     $field = field_info_field_by_id($field_id);
1771     $field_name = $field['field_name'];
1772     $table_name = _field_sql_storage_tablename($field);
1773     $revision_name = _field_sql_storage_revision_tablename($field);
1774
1775     $all_languages = field_available_languages($entity_type, $field);
1776     $field_languages = array_intersect($all_languages, array_keys((array) $entity->$field_name));
1777
1778     // Delete and insert, rather than update, in case a value was added.
1779     if ($op == FIELD_STORAGE_UPDATE) {
1780       // Delete languages present in the incoming $entity->$field_name.
1781       // Delete all languages if $entity->$field_name is empty.
1782       $languages = !empty($entity->$field_name) ? $field_languages : $all_languages;
1783       if ($languages) {
1784         db_delete($table_name)
1785           ->condition('entity_type', $entity_type)
1786           ->condition('entity_id', $id)
1787           ->condition('language', $languages, 'IN')
1788           ->execute();
1789         db_delete($revision_name)
1790           ->condition('entity_type', $entity_type)
1791           ->condition('entity_id', $id)
1792           ->condition('revision_id', $vid)
1793           ->condition('language', $languages, 'IN')
1794           ->execute();
1795       }
1796     }
1797
1798     // Prepare the multi-insert query.
1799     $do_insert = FALSE;
1800     $columns = array('entity_type', 'entity_id', 'revision_id', 'bundle', 'delta', 'language');
1801     foreach ($field['columns'] as $column => $attributes) {
1802       $columns[] = _field_sql_storage_columnname($field_name, $column);
1803     }
1804     $query = db_insert($table_name)->fields($columns);
1805     $revision_query = db_insert($revision_name)->fields($columns);
1806
1807     foreach ($field_languages as $langcode) {
1808       $items = (array) $entity->{$field_name}[$langcode];
1809       $delta_count = 0;
1810       foreach ($items as $delta => $item) {
1811         // We now know we have someting to insert.
1812         $do_insert = TRUE;
1813         $record = array(
1814           'entity_type' => $entity_type,
1815           'entity_id' => $id,
1816           'revision_id' => $vid,
1817           'bundle' => $bundle,
1818           'delta' => $delta,
1819           'language' => $langcode,
1820         );
1821         foreach ($field['columns'] as $column => $attributes) {
1822           $record[_field_sql_storage_columnname($field_name, $column)] = isset($item[$column]) ? $item[$column] : NULL;
1823         }
1824         $query->values($record);
1825         if (isset($vid)) {
1826           $revision_query->values($record);
1827         }
1828
1829         if ($field['cardinality'] != FIELD_CARDINALITY_UNLIMITED && ++$delta_count == $field['cardinality']) {
1830           break;
1831         }
1832       }
1833     }
1834
1835     // Execute the query if we have values to insert.
1836     if ($do_insert) {
1837       $query->execute();
1838       $revision_query->execute();
1839     }
1840   }
1841 }
1842
1843 /**
1844  * Delete all field data for an entity.
1845  *
1846  * This hook is invoked from field_attach_delete() to ask the field storage
1847  * module to delete field data.
1848  *
1849  * @param $entity_type
1850  *   The entity type of entity, such as 'node' or 'user'.
1851  * @param $entity
1852  *   The entity on which to operate.
1853  * @param $fields
1854  *   An array listing the fields to delete. The keys and values of the
1855  *   array are field IDs.
1856  */
1857 function hook_field_storage_delete($entity_type, $entity, $fields) {
1858   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
1859
1860   foreach (field_info_instances($entity_type, $bundle) as $instance) {
1861     if (isset($fields[$instance['field_id']])) {
1862       $field = field_info_field_by_id($instance['field_id']);
1863       field_sql_storage_field_storage_purge($entity_type, $entity, $field, $instance);
1864     }
1865   }
1866 }
1867
1868 /**
1869  * Delete a single revision of field data for an entity.
1870  *
1871  * This hook is invoked from field_attach_delete_revision() to ask the field
1872  * storage module to delete field revision data.
1873  *
1874  * Deleting the current (most recently written) revision is not
1875  * allowed as has undefined results.
1876  *
1877  * @param $entity_type
1878  *   The entity type of entity, such as 'node' or 'user'.
1879  * @param $entity
1880  *   The entity on which to operate. The revision to delete is
1881  *   indicated by the entity's revision ID property, as identified by
1882  *   hook_fieldable_info() for $entity_type.
1883  * @param $fields
1884  *   An array listing the fields to delete. The keys and values of the
1885  *   array are field IDs.
1886  */
1887 function hook_field_storage_delete_revision($entity_type, $entity, $fields) {
1888   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
1889
1890   if (isset($vid)) {
1891     foreach ($fields as $field_id) {
1892       $field = field_info_field_by_id($field_id);
1893       $revision_name = _field_sql_storage_revision_tablename($field);
1894       db_delete($revision_name)
1895         ->condition('entity_type', $entity_type)
1896         ->condition('entity_id', $id)
1897         ->condition('revision_id', $vid)
1898         ->execute();
1899     }
1900   }
1901 }
1902
1903 /**
1904  * Execute an EntityFieldQuery.
1905  *
1906  * This hook is called to find the entities having certain entity and field
1907  * conditions and sort them in the given field order. If the field storage
1908  * engine also handles property sorts and orders, it should unset those
1909  * properties in the called object to signal that those have been handled.
1910  *
1911  * @param EntityFieldQuery $query
1912  *   An EntityFieldQuery.
1913  *
1914  * @return
1915  *   See EntityFieldQuery::execute() for the return values.
1916  */
1917 function hook_field_storage_query($query) {
1918   $groups = array();
1919   if ($query->age == FIELD_LOAD_CURRENT) {
1920     $tablename_function = '_field_sql_storage_tablename';
1921     $id_key = 'entity_id';
1922   }
1923   else {
1924     $tablename_function = '_field_sql_storage_revision_tablename';
1925     $id_key = 'revision_id';
1926   }
1927   $table_aliases = array();
1928   // Add tables for the fields used.
1929   foreach ($query->fields as $key => $field) {
1930     $tablename = $tablename_function($field);
1931     // Every field needs a new table.
1932     $table_alias = $tablename . $key;
1933     $table_aliases[$key] = $table_alias;
1934     if ($key) {
1935       $select_query->join($tablename, $table_alias, "$table_alias.entity_type = $field_base_table.entity_type AND $table_alias.$id_key = $field_base_table.$id_key");
1936     }
1937     else {
1938       $select_query = db_select($tablename, $table_alias);
1939       $select_query->addTag('entity_field_access');
1940       $select_query->addMetaData('base_table', $tablename);
1941       $select_query->fields($table_alias, array('entity_type', 'entity_id', 'revision_id', 'bundle'));
1942       $field_base_table = $table_alias;
1943     }
1944     if ($field['cardinality'] != 1) {
1945       $select_query->distinct();
1946     }
1947   }
1948
1949   // Add field conditions.
1950   foreach ($query->fieldConditions as $key => $condition) {
1951     $table_alias = $table_aliases[$key];
1952     $field = $condition['field'];
1953     // Add the specified condition.
1954     $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $condition['column']);
1955     $query->addCondition($select_query, $sql_field, $condition);
1956     // Add delta / language group conditions.
1957     foreach (array('delta', 'language') as $column) {
1958       if (isset($condition[$column . '_group'])) {
1959         $group_name = $condition[$column . '_group'];
1960         if (!isset($groups[$column][$group_name])) {
1961           $groups[$column][$group_name] = $table_alias;
1962         }
1963         else {
1964           $select_query->where("$table_alias.$column = " . $groups[$column][$group_name] . ".$column");
1965         }
1966       }
1967     }
1968   }
1969
1970   if (isset($query->deleted)) {
1971     $select_query->condition("$field_base_table.deleted", (int) $query->deleted);
1972   }
1973
1974   // Is there a need to sort the query by property?
1975   $has_property_order = FALSE;
1976   foreach ($query->order as $order) {
1977     if ($order['type'] == 'property') {
1978       $has_property_order = TRUE;
1979     }
1980   }
1981
1982   if ($query->propertyConditions || $has_property_order) {
1983     if (empty($query->entityConditions['entity_type']['value'])) {
1984       throw new EntityFieldQueryException('Property conditions and orders must have an entity type defined.');
1985     }
1986     $entity_type = $query->entityConditions['entity_type']['value'];
1987     $entity_base_table = _field_sql_storage_query_join_entity($select_query, $entity_type, $field_base_table);
1988     $query->entityConditions['entity_type']['operator'] = '=';
1989     foreach ($query->propertyConditions as $property_condition) {
1990       $query->addCondition($select_query, "$entity_base_table." . $property_condition['column'], $property_condition);
1991     }
1992   }
1993   foreach ($query->entityConditions as $key => $condition) {
1994     $query->addCondition($select_query, "$field_base_table.$key", $condition);
1995   }
1996
1997   // Order the query.
1998   foreach ($query->order as $order) {
1999     if ($order['type'] == 'entity') {
2000       $key = $order['specifier'];
2001       $select_query->orderBy("$field_base_table.$key", $order['direction']);
2002     }
2003     elseif ($order['type'] == 'field') {
2004       $specifier = $order['specifier'];
2005       $field = $specifier['field'];
2006       $table_alias = $table_aliases[$specifier['index']];
2007       $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $specifier['column']);
2008       $select_query->orderBy($sql_field, $order['direction']);
2009     }
2010     elseif ($order['type'] == 'property') {
2011       $select_query->orderBy("$entity_base_table." . $order['specifier'], $order['direction']);
2012     }
2013   }
2014
2015   return $query->finishQuery($select_query, $id_key);
2016 }
2017
2018 /**
2019  * Act on creation of a new field.
2020  *
2021  * This hook is invoked from field_create_field() to ask the field storage
2022  * module to save field information and prepare for storing field instances.
2023  * If there is a problem, the field storage module should throw an exception.
2024  *
2025  * @param $field
2026  *   The field structure being created.
2027  */
2028 function hook_field_storage_create_field($field) {
2029   $schema = _field_sql_storage_schema($field);
2030   foreach ($schema as $name => $table) {
2031     db_create_table($name, $table);
2032   }
2033   drupal_get_schema(NULL, TRUE);
2034 }
2035
2036 /**
2037  * Act on deletion of a field.
2038  *
2039  * This hook is invoked from field_delete_field() to ask the field storage
2040  * module to mark all information stored in the field for deletion.
2041  *
2042  * @param $field
2043  *   The field being deleted.
2044  */
2045 function hook_field_storage_delete_field($field) {
2046   // Mark all data associated with the field for deletion.
2047   $field['deleted'] = 0;
2048   $table = _field_sql_storage_tablename($field);
2049   $revision_table = _field_sql_storage_revision_tablename($field);
2050   db_update($table)
2051     ->fields(array('deleted' => 1))
2052     ->execute();
2053
2054   // Move the table to a unique name while the table contents are being deleted.
2055   $field['deleted'] = 1;
2056   $new_table = _field_sql_storage_tablename($field);
2057   $revision_new_table = _field_sql_storage_revision_tablename($field);
2058   db_rename_table($table, $new_table);
2059   db_rename_table($revision_table, $revision_new_table);
2060   drupal_get_schema(NULL, TRUE);
2061 }
2062
2063 /**
2064  * Act on deletion of a field instance.
2065  *
2066  * This hook is invoked from field_delete_instance() to ask the field storage
2067  * module to mark all information stored for the field instance for deletion.
2068  *
2069  * @param $instance
2070  *   The instance being deleted.
2071  */
2072 function hook_field_storage_delete_instance($instance) {
2073   $field = field_info_field($instance['field_name']);
2074   $table_name = _field_sql_storage_tablename($field);
2075   $revision_name = _field_sql_storage_revision_tablename($field);
2076   db_update($table_name)
2077     ->fields(array('deleted' => 1))
2078     ->condition('entity_type', $instance['entity_type'])
2079     ->condition('bundle', $instance['bundle'])
2080     ->execute();
2081   db_update($revision_name)
2082     ->fields(array('deleted' => 1))
2083     ->condition('entity_type', $instance['entity_type'])
2084     ->condition('bundle', $instance['bundle'])
2085     ->execute();
2086 }
2087
2088 /**
2089  * Act before the storage backends load field data.
2090  *
2091  * This hook allows modules to load data before the Field Storage API,
2092  * optionally preventing the field storage module from doing so.
2093  *
2094  * This lets 3rd party modules override, mirror, shard, or otherwise store a
2095  * subset of fields in a different way than the current storage engine.
2096  * Possible use cases include per-bundle storage, per-combo-field storage, etc.
2097  *
2098  * Modules implementing this hook should load field values and add them to
2099  * objects in $entities. Fields with no values should be added as empty
2100  * arrays. In addition, fields loaded should be added as keys to $skip_fields.
2101  *
2102  * @param $entity_type
2103  *   The type of entity, such as 'node' or 'user'.
2104  * @param $entities
2105  *   The array of entity objects to add fields to, keyed by entity ID.
2106  * @param $age
2107  *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
2108  *   FIELD_LOAD_REVISION to load the version indicated by each entity.
2109  * @param $skip_fields
2110  *   An array keyed by field IDs whose data has already been loaded and
2111  *   therefore should not be loaded again. Add a key to this array to indicate
2112  *   that your module has already loaded a field.
2113  * @param $options
2114  *   An associative array of additional options, with the following keys:
2115  *   - field_id: The field ID that should be loaded. If unset, all fields
2116  *     should be loaded.
2117  *   - deleted: If TRUE, deleted fields should be loaded as well as
2118  *     non-deleted fields. If unset or FALSE, only non-deleted fields should be
2119  *     loaded.
2120  */
2121 function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) {
2122   // @todo Needs function body.
2123 }
2124
2125 /**
2126  * Act before the storage backends insert field data.
2127  *
2128  * This hook allows modules to store data before the Field Storage API,
2129  * optionally preventing the field storage module from doing so.
2130  *
2131  * @param $entity_type
2132  *   The type of $entity; for example, 'node' or 'user'.
2133  * @param $entity
2134  *   The entity with fields to save.
2135  * @param $skip_fields
2136  *   An array keyed by field IDs whose data has already been written and
2137  *   therefore should not be written again. The values associated with these
2138  *   keys are not specified.
2139  * @return
2140  *   Saved field IDs are set set as keys in $skip_fields.
2141  */
2142 function hook_field_storage_pre_insert($entity_type, $entity, &$skip_fields) {
2143   if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) {
2144     $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp'));
2145     foreach ($entity->taxonomy_forums as $language) {
2146       foreach ($language as $delta) {
2147         $query->values(array(
2148           'nid' => $entity->nid,
2149           'title' => $entity->title,
2150           'tid' => $delta['value'],
2151           'sticky' => $entity->sticky,
2152           'created' => $entity->created,
2153           'comment_count' => 0,
2154           'last_comment_timestamp' => $entity->created,
2155         ));
2156       }
2157     }
2158     $query->execute();
2159   }
2160 }
2161
2162 /**
2163  * Act before the storage backends update field data.
2164  *
2165  * This hook allows modules to store data before the Field Storage API,
2166  * optionally preventing the field storage module from doing so.
2167  *
2168  * @param $entity_type
2169  *   The type of $entity; for example, 'node' or 'user'.
2170  * @param $entity
2171  *   The entity with fields to save.
2172  * @param $skip_fields
2173  *   An array keyed by field IDs whose data has already been written and
2174  *   therefore should not be written again. The values associated with these
2175  *   keys are not specified.
2176  * @return
2177  *   Saved field IDs are set set as keys in $skip_fields.
2178  */
2179 function hook_field_storage_pre_update($entity_type, $entity, &$skip_fields) {
2180   $first_call = &drupal_static(__FUNCTION__, array());
2181
2182   if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) {
2183     // We don't maintain data for old revisions, so clear all previous values
2184     // from the table. Since this hook runs once per field, per entity, make
2185     // sure we only wipe values once.
2186     if (!isset($first_call[$entity->nid])) {
2187       $first_call[$entity->nid] = FALSE;
2188       db_delete('forum_index')->condition('nid', $entity->nid)->execute();
2189     }
2190     // Only save data to the table if the node is published.
2191     if ($entity->status) {
2192       $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp'));
2193       foreach ($entity->taxonomy_forums as $language) {
2194         foreach ($language as $delta) {
2195           $query->values(array(
2196             'nid' => $entity->nid,
2197             'title' => $entity->title,
2198             'tid' => $delta['value'],
2199             'sticky' => $entity->sticky,
2200             'created' => $entity->created,
2201             'comment_count' => 0,
2202             'last_comment_timestamp' => $entity->created,
2203           ));
2204         }
2205       }
2206       $query->execute();
2207       // The logic for determining last_comment_count is fairly complex, so
2208       // call _forum_update_forum_index() too.
2209       _forum_update_forum_index($entity->nid);
2210     }
2211   }
2212 }
2213
2214 /**
2215  * Returns the maximum weight for the entity components handled by the module.
2216  *
2217  * Field API takes care of fields and 'extra_fields'. This hook is intended for
2218  * third-party modules adding other entity components (e.g. field_group).
2219  *
2220  * @param $entity_type
2221  *   The type of entity; e.g. 'node' or 'user'.
2222  * @param $bundle
2223  *   The bundle name.
2224  * @param $context
2225  *   The context for which the maximum weight is requested. Either 'form', or
2226  *   the name of a view mode.
2227  * @return
2228  *   The maximum weight of the entity's components, or NULL if no components
2229  *   were found.
2230  */
2231 function hook_field_info_max_weight($entity_type, $bundle, $context) {
2232   $weights = array();
2233
2234   foreach (my_module_entity_additions($entity_type, $bundle, $context) as $addition) {
2235     $weights[] = $addition['weight'];
2236   }
2237
2238   return $weights ? max($weights) : NULL;
2239 }
2240
2241 /**
2242  * Alters the display settings of a field before it gets displayed.
2243  *
2244  * Note that instead of hook_field_display_alter(), which is called for all
2245  * fields on all entity types, hook_field_display_ENTITY_TYPE_alter() may be
2246  * used to alter display settings for fields on a specific entity type only.
2247  *
2248  * This hook is called once per field per displayed entity. If the result of the
2249  * hook involves reading from the database, it is highly recommended to
2250  * statically cache the information.
2251  *
2252  * @param $display
2253  *   The display settings that will be used to display the field values, as
2254  *   found in the 'display' key of $instance definitions.
2255  * @param $context
2256  *   An associative array containing:
2257  *   - entity_type: The entity type; e.g., 'node' or 'user'.
2258  *   - field: The field being rendered.
2259  *   - instance: The instance being rendered.
2260  *   - entity: The entity being rendered.
2261  *   - view_mode: The view mode, e.g. 'full', 'teaser'...
2262  *
2263  * @see hook_field_display_ENTITY_TYPE_alter()
2264  */
2265 function hook_field_display_alter(&$display, $context) {
2266   // Leave field labels out of the search index.
2267   // Note: The check against $context['entity_type'] == 'node' could be avoided
2268   // by using hook_field_display_node_alter() instead of
2269   // hook_field_display_alter(), resulting in less function calls when
2270   // rendering non-node entities.
2271   if ($context['entity_type'] == 'node' && $context['view_mode'] == 'search_index') {
2272     $display['label'] = 'hidden';
2273   }
2274 }
2275
2276 /**
2277  * Alters the display settings of a field on a given entity type before it gets displayed.
2278  *
2279  * Modules can implement hook_field_display_ENTITY_TYPE_alter() to alter display
2280  * settings for fields on a specific entity type, rather than implementing
2281  * hook_field_display_alter().
2282  *
2283  * This hook is called once per field per displayed entity. If the result of the
2284  * hook involves reading from the database, it is highly recommended to
2285  * statically cache the information.
2286  *
2287  * @param $display
2288  *   The display settings that will be used to display the field values, as
2289  *   found in the 'display' key of $instance definitions.
2290  * @param $context
2291  *   An associative array containing:
2292  *   - entity_type: The entity type; e.g., 'node' or 'user'.
2293  *   - field: The field being rendered.
2294  *   - instance: The instance being rendered.
2295  *   - entity: The entity being rendered.
2296  *   - view_mode: The view mode, e.g. 'full', 'teaser'...
2297  *
2298  * @see hook_field_display_alter()
2299  */
2300 function hook_field_display_ENTITY_TYPE_alter(&$display, $context) {
2301   // Leave field labels out of the search index.
2302   if ($context['view_mode'] == 'search_index') {
2303     $display['label'] = 'hidden';
2304   }
2305 }
2306
2307 /**
2308  * Alters the display settings of pseudo-fields before an entity is displayed.
2309  *
2310  * This hook is called once per displayed entity. If the result of the hook
2311  * involves reading from the database, it is highly recommended to statically
2312  * cache the information.
2313  *
2314  * @param $displays
2315  *   An array of display settings for the pseudo-fields in the entity, keyed
2316  *   by pseudo-field names.
2317  * @param $context
2318  *   An associative array containing:
2319  *   - entity_type: The entity type; e.g., 'node' or 'user'.
2320  *   - bundle: The bundle name.
2321  *   - view_mode: The view mode, e.g. 'full', 'teaser'...
2322  */
2323 function hook_field_extra_fields_display_alter(&$displays, $context) {
2324   if ($context['entity_type'] == 'taxonomy_term' && $context['view_mode'] == 'full') {
2325     $displays['description']['visible'] = FALSE;
2326   }
2327 }
2328
2329 /**
2330  * Alters the widget properties of a field instance before it gets displayed.
2331  *
2332  * Note that instead of hook_field_widget_properties_alter(), which is called
2333  * for all fields on all entity types,
2334  * hook_field_widget_properties_ENTITY_TYPE_alter() may be used to alter widget
2335  * properties for fields on a specific entity type only.
2336  *
2337  * This hook is called once per field per added or edit entity. If the result
2338  * of the hook involves reading from the database, it is highly recommended to
2339  * statically cache the information.
2340  *
2341  * @param $widget
2342  *   The instance's widget properties.
2343  * @param $context
2344  *   An associative array containing:
2345  *   - entity_type: The entity type; e.g., 'node' or 'user'.
2346  *   - entity: The entity object.
2347  *   - field: The field that the widget belongs to.
2348  *   - instance: The instance of the field.
2349  *
2350  * @see hook_field_widget_properties_ENTITY_TYPE_alter()
2351  */
2352 function hook_field_widget_properties_alter(&$widget, $context) {
2353   // Change a widget's type according to the time of day.
2354   $field = $context['field'];
2355   if ($context['entity_type'] == 'node' && $field['field_name'] == 'field_foo') {
2356     $time = date('H');
2357     $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm';
2358   }
2359 }
2360
2361 /**
2362  * Alters the widget properties of a field instance on a given entity type
2363  * before it gets displayed.
2364  *
2365  * Modules can implement hook_field_widget_properties_ENTITY_TYPE_alter() to
2366  * alter the widget properties for fields on a specific entity type, rather than
2367  * implementing hook_field_widget_properties_alter().
2368  *
2369  * This hook is called once per field per displayed widget entity. If the result
2370  * of the hook involves reading from the database, it is highly recommended to
2371  * statically cache the information.
2372  *
2373  * @param $widget
2374  *   The instance's widget properties.
2375  * @param $context
2376  *   An associative array containing:
2377  *   - entity_type: The entity type; e.g., 'node' or 'user'.
2378  *   - entity: The entity object.
2379  *   - field: The field that the widget belongs to.
2380  *   - instance: The instance of the field.
2381  *
2382  * @see hook_field_widget_properties_alter()
2383  */
2384 function hook_field_widget_properties_ENTITY_TYPE_alter(&$widget, $context) {
2385   // Change a widget's type according to the time of day.
2386   $field = $context['field'];
2387   if ($field['field_name'] == 'field_foo') {
2388     $time = date('H');
2389     $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm';
2390   }
2391 }
2392
2393 /**
2394  * @} End of "ingroup field_storage"
2395  */
2396
2397 /**
2398  * @ingroup field_crud
2399  * @{
2400  */
2401
2402 /**
2403  * Act on a field being created.
2404  *
2405  * This hook is invoked from field_create_field() after the field is created, to
2406  * allow modules to act on field creation.
2407  *
2408  * @param $field
2409  *   The field just created.
2410  */
2411 function hook_field_create_field($field) {
2412   // @todo Needs function body.
2413 }
2414
2415 /**
2416  * Act on a field instance being created.
2417  *
2418  * This hook is invoked from field_create_instance() after the instance record
2419  * is saved, so it cannot be used to modify the instance itself.
2420  *
2421  * @param $instance
2422  *   The instance just created.
2423  */
2424 function hook_field_create_instance($instance) {
2425   // @todo Needs function body.
2426 }
2427
2428 /**
2429  * Forbid a field update from occurring.
2430  *
2431  * Any module may forbid any update for any reason. For example, the
2432  * field's storage module might forbid an update if it would change
2433  * the storage schema while data for the field exists. A field type
2434  * module might forbid an update if it would change existing data's
2435  * semantics, or if there are external dependencies on field settings
2436  * that cannot be updated.
2437  *
2438  * To forbid the update from occurring, throw a FieldUpdateForbiddenException.
2439  *
2440  * @param $field
2441  *   The field as it will be post-update.
2442  * @param $prior_field
2443  *   The field as it is pre-update.
2444  * @param $has_data
2445  *   Whether any data already exists for this field.
2446  */
2447 function hook_field_update_forbid($field, $prior_field, $has_data) {
2448   // A 'list' field stores integer keys mapped to display values. If
2449   // the new field will have fewer values, and any data exists for the
2450   // abandoned keys, the field will have no way to display them. So,
2451   // forbid such an update.
2452   if ($has_data && count($field['settings']['allowed_values']) < count($prior_field['settings']['allowed_values'])) {
2453     // Identify the keys that will be lost.
2454     $lost_keys = array_diff(array_keys($field['settings']['allowed_values']), array_keys($prior_field['settings']['allowed_values']));
2455     // If any data exist for those keys, forbid the update.
2456     $query = new EntityFieldQuery();
2457     $found = $query
2458       ->fieldCondition($prior_field['field_name'], 'value', $lost_keys)
2459       ->range(0, 1)
2460       ->execute();
2461     if ($found) {
2462       throw new FieldUpdateForbiddenException("Cannot update a list field not to include keys with existing data");
2463     }
2464   }
2465 }
2466
2467 /**
2468  * Act on a field being updated.
2469  *
2470  * This hook is invoked just after field is updated in field_update_field().
2471  *
2472  * @param $field
2473  *   The field as it is post-update.
2474  * @param $prior_field
2475  *   The field as it was pre-update.
2476  * @param $has_data
2477  *   Whether any data already exists for this field.
2478  */
2479 function hook_field_update_field($field, $prior_field, $has_data) {
2480   // Reset the static value that keeps track of allowed values for list fields.
2481   drupal_static_reset('list_allowed_values');
2482 }
2483
2484 /**
2485  * Act on a field being deleted.
2486  *
2487  * This hook is invoked just after a field is deleted by field_delete_field().
2488  *
2489  * @param $field
2490  *   The field just deleted.
2491  */
2492 function hook_field_delete_field($field) {
2493   // @todo Needs function body.
2494 }
2495
2496 /**
2497  * Act on a field instance being updated.
2498  *
2499  * This hook is invoked from field_update_instance() after the instance record
2500  * is saved, so it cannot be used by a module to modify the instance itself.
2501  *
2502  * @param $instance
2503  *   The instance as it is post-update.
2504  * @param $prior_$instance
2505  *   The instance as it was pre-update.
2506  */
2507 function hook_field_update_instance($instance, $prior_instance) {
2508   // @todo Needs function body.
2509 }
2510
2511 /**
2512  * Act on a field instance being deleted.
2513  *
2514  * This hook is invoked from field_delete_instance() after the instance is
2515  * deleted.
2516  *
2517  * @param $instance
2518  *   The instance just deleted.
2519  */
2520 function hook_field_delete_instance($instance) {
2521   // @todo Needs function body.
2522 }
2523
2524 /**
2525  * Act on field records being read from the database.
2526  *
2527  * This hook is invoked from field_read_fields() on each field being read.
2528  *
2529  * @param $field
2530  *   The field record just read from the database.
2531  */
2532 function hook_field_read_field($field) {
2533   // @todo Needs function body.
2534 }
2535
2536 /**
2537  * Act on a field record being read from the database.
2538  *
2539  * This hook is invoked from field_read_instances() on each instance being read.
2540  *
2541  * @param $instance
2542  *   The instance record just read from the database.
2543  */
2544 function hook_field_read_instance($instance) {
2545   // @todo Needs function body.
2546 }
2547
2548 /**
2549  * Acts when a field record is being purged.
2550  *
2551  * In field_purge_field(), after the field configuration has been
2552  * removed from the database, the field storage module has had a chance to
2553  * run its hook_field_storage_purge_field(), and the field info cache
2554  * has been cleared, this hook is invoked on all modules to allow them to
2555  * respond to the field being purged.
2556  *
2557  * @param $field
2558  *   The field being purged.
2559  */
2560 function hook_field_purge_field($field) {
2561   db_delete('my_module_field_info')
2562     ->condition('id', $field['id'])
2563     ->execute();
2564 }
2565
2566 /**
2567  * Acts when a field instance is being purged.
2568  *
2569  * In field_purge_instance(), after the field instance has been
2570  * removed from the database, the field storage module has had a chance to
2571  * run its hook_field_storage_purge_instance(), and the field info cache
2572  * has been cleared, this hook is invoked on all modules to allow them to
2573  * respond to the field instance being purged.
2574  *
2575  * @param $instance
2576  *   The instance being purged.
2577  */
2578 function hook_field_purge_instance($instance) {
2579   db_delete('my_module_field_instance_info')
2580     ->condition('id', $instance['id'])
2581     ->execute();
2582 }
2583
2584 /**
2585  * Remove field storage information when a field record is purged.
2586  *
2587  * Called from field_purge_field() to allow the field storage module
2588  * to remove field information when a field is being purged.
2589  *
2590  * @param $field
2591  *   The field being purged.
2592  */
2593 function hook_field_storage_purge_field($field) {
2594   $table_name = _field_sql_storage_tablename($field);
2595   $revision_name = _field_sql_storage_revision_tablename($field);
2596   db_drop_table($table_name);
2597   db_drop_table($revision_name);
2598 }
2599
2600 /**
2601  * Remove field storage information when a field instance is purged.
2602  *
2603  * Called from field_purge_instance() to allow the field storage module
2604  * to remove field instance information when a field instance is being
2605  * purged.
2606  *
2607  * @param $instance
2608  *   The instance being purged.
2609  */
2610 function hook_field_storage_purge_field_instance($instance) {
2611   db_delete('my_module_field_instance_info')
2612     ->condition('id', $instance['id'])
2613     ->execute();
2614 }
2615
2616 /**
2617  * Remove field storage information when field data is purged.
2618  *
2619  * Called from field_purge_data() to allow the field storage
2620  * module to delete field data information.
2621  *
2622  * @param $entity_type
2623  *   The type of $entity; for example, 'node' or 'user'.
2624  * @param $entity
2625  *   The pseudo-entity whose field data to delete.
2626  * @param $field
2627  *   The (possibly deleted) field whose data is being purged.
2628  * @param $instance
2629  *   The deleted field instance whose data is being purged.
2630  */
2631 function hook_field_storage_purge($entity_type, $entity, $field, $instance) {
2632   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
2633
2634   $table_name = _field_sql_storage_tablename($field);
2635   $revision_name = _field_sql_storage_revision_tablename($field);
2636   db_delete($table_name)
2637     ->condition('entity_type', $entity_type)
2638     ->condition('entity_id', $id)
2639     ->execute();
2640   db_delete($revision_name)
2641     ->condition('entity_type', $entity_type)
2642     ->condition('entity_id', $id)
2643     ->execute();
2644 }
2645
2646 /**
2647  * @} End of "ingroup field_crud"
2648  */
2649
2650 /**
2651  * Determine whether the user has access to a given field.
2652  *
2653  * This hook is invoked from field_access() to let modules block access to
2654  * operations on fields. If no module returns FALSE, the operation is allowed.
2655  *
2656  * @param $op
2657  *   The operation to be performed. Possible values: 'edit', 'view'.
2658  * @param $field
2659  *   The field on which the operation is to be performed.
2660  * @param $entity_type
2661  *   The type of $entity; for example, 'node' or 'user'.
2662  * @param $entity
2663  *   (optional) The entity for the operation.
2664  * @param $account
2665  *   (optional) The account to check; if not given use currently logged in user.
2666  *
2667  * @return
2668  *   TRUE if the operation is allowed, and FALSE if the operation is denied.
2669  */
2670 function hook_field_access($op, $field, $entity_type, $entity, $account) {
2671   if ($field['field_name'] == 'field_of_interest' && $op == 'edit') {
2672     return user_access('edit field of interest', $account);
2673   }
2674   return TRUE;
2675 }
2676
2677 /**
2678  * @} End of "addtogroup hooks"
2679  */