field.api.php

  1. cis7 modules/field/field.api.php
  2. cle7 modules/field/field.api.php
  3. ecd7 modules/field/field.api.php
  4. elmsmedia7 modules/field/field.api.php
  5. harmony7 modules/field/field.api.php
  6. icor7 modules/field/field.api.php
  7. meedjum_blog7 modules/field/field.api.php
  8. mooc7 modules/field/field.api.php

Functions

Namesort descending Description
hook_field_access Determine whether the user has access to a given field.
hook_field_attach_create_bundle Act on field_attach_create_bundle().
hook_field_attach_delete Act on field_attach_delete().
hook_field_attach_delete_bundle Act on field_attach_delete_bundle.
hook_field_attach_delete_revision Act on field_attach_delete_revision().
hook_field_attach_form Act on field_attach_form().
hook_field_attach_insert Act on field_attach_insert().
hook_field_attach_load Act on field_attach_load().
hook_field_attach_prepare_translation_alter Perform alterations on field_attach_prepare_translation().
hook_field_attach_preprocess_alter Alter field_attach_preprocess() variables.
hook_field_attach_presave Act on field_attach_presave().
hook_field_attach_purge Act on field_purge_data().
hook_field_attach_rename_bundle Act on field_attach_rename_bundle().
hook_field_attach_submit Act on field_attach_submit().
hook_field_attach_update Act on field_attach_update().
hook_field_attach_validate Act on field_attach_validate().
hook_field_attach_view_alter Perform alterations on field_attach_view() or field_view_field().
hook_field_available_languages_alter Alter field_available_languages() values.
hook_field_create_field Act on a field being created.
hook_field_create_instance Act on a field instance being created.
hook_field_delete Define custom delete behavior for this module's field data.
hook_field_delete_field Act on a field being deleted.
hook_field_delete_instance Act on a field instance being deleted.
hook_field_delete_revision Define custom revision delete behavior for this module's field types.
hook_field_display_alter Alters the display settings of a field before it gets displayed.
hook_field_display_ENTITY_TYPE_alter Alters the display settings of a field on a given entity type before it gets displayed.
hook_field_extra_fields Exposes "pseudo-field" components on fieldable entities.
hook_field_extra_fields_alter Alter "pseudo-field" components on fieldable entities.
hook_field_extra_fields_display_alter Alters the display settings of pseudo-fields before an entity is displayed.
hook_field_formatter_info Expose Field API formatter types.
hook_field_formatter_info_alter Perform alterations on Field API formatter types.
hook_field_formatter_prepare_view Allow formatters to load information for field values being displayed.
hook_field_formatter_view Build a renderable array for a field value.
hook_field_info Define Field API field types.
hook_field_info_alter Perform alterations on Field API field types.
hook_field_info_max_weight Returns the maximum weight for the entity components handled by the module.
hook_field_insert Define custom insert behavior for this module's field data.
hook_field_is_empty Define what constitutes an empty item for a field type.
hook_field_language_alter Perform alterations on field_language() values.
hook_field_load Define custom load behavior for this module's field types.
hook_field_prepare_translation Define custom prepare_translation behavior for this module's field types.
hook_field_prepare_view Prepare field values prior to display.
hook_field_presave Define custom presave behavior for this module's field types.
hook_field_purge_field Acts when a field record is being purged.
hook_field_purge_instance Acts when a field instance is being purged.
hook_field_read_field Act on field records being read from the database.
hook_field_read_instance Act on a field record being read from the database.
hook_field_schema Define the Field API schema for a field structure.
hook_field_storage_create_field Act on creation of a new field.
hook_field_storage_delete Delete all field data for an entity.
hook_field_storage_delete_field Act on deletion of a field.
hook_field_storage_delete_instance Act on deletion of a field instance.
hook_field_storage_delete_revision Delete a single revision of field data for an entity.
hook_field_storage_details Reveal the internal details about the storage for a field.
hook_field_storage_details_alter Perform alterations on Field API storage details.
hook_field_storage_info Expose Field API storage backends.
hook_field_storage_info_alter Perform alterations on Field API storage types.
hook_field_storage_load Load field data for a set of entities.
hook_field_storage_pre_insert Act before the storage backends insert field data.
hook_field_storage_pre_load Act before the storage backends load field data.
hook_field_storage_pre_update Act before the storage backends update field data.
hook_field_storage_purge Remove field storage information when field data is purged.
hook_field_storage_purge_field Remove field storage information when a field record is purged.
hook_field_storage_purge_field_instance Remove field storage information when a field instance is purged.
hook_field_storage_query Execute an EntityFieldQuery.
hook_field_storage_update_field Update the storage information for a field.
hook_field_storage_write Write field data for an entity.
hook_field_update Define custom update behavior for this module's field data.
hook_field_update_field Act on a field being updated.
hook_field_update_forbid Forbid a field update from occurring.
hook_field_update_instance Act on a field instance being updated.
hook_field_validate Validate this module's field data.
hook_field_widget_error Flag a field-level validation error.
hook_field_widget_form Return the form for a single field widget.
hook_field_widget_form_alter Alter forms for field widgets provided by other modules.
hook_field_widget_info Expose Field API widget types.
hook_field_widget_info_alter Perform alterations on Field API widget types.
hook_field_widget_properties_alter Alters the widget properties of a field instance before it gets displayed.
hook_field_widget_properties_ENTITY_TYPE_alter Alters the widget properties of a field instance on a given entity type before it gets displayed.
hook_field_widget_WIDGET_TYPE_form_alter Alter widget forms for a specific widget provided by another module.

File

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