field.api.php

File

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

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.