diff options
| -rw-r--r-- | modules/field/field.api.php | 58 | ||||
| -rw-r--r-- | modules/field/field.attach.inc | 53 |
2 files changed, 59 insertions, 52 deletions
diff --git a/modules/field/field.api.php b/modules/field/field.api.php index d8752ba62..357db8f10 100644 --- a/modules/field/field.api.php +++ b/modules/field/field.api.php @@ -1224,23 +1224,28 @@ function hook_field_storage_details_alter(&$details, $field) { /** * Load field data for a set of entities. * + * Modules implementing this hook should load field values and add them to + * objects in $entities. Fields with no values should be added as empty + * arrays. + * * @param $entity_type - * The entity type of entity, such as 'node' or 'user'. + * The type of entity, such as 'node' or 'user'. * @param $entities - * The array of entities for which to load data, keyed by entity id. + * The array of entity objects to add fields to, keyed by entity ID. * @param $age - * FIELD_LOAD_CURRENT to load the most recent revision for all - * fields, or FIELD_LOAD_REVISION to load the version indicated by - * each entity. + * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or + * FIELD_LOAD_REVISION to load the version indicated by each entity. * @param $fields * An array listing the fields to be loaded. The keys of the array are field - * ids, the values of the array are the entity ids (or revision ids, - * depending on the $age parameter) to be loaded for each field. - * @return - * Loaded field values are added to $entities. Fields with no values should be - * set as an empty array. + * IDs, and the values of the array are the entity IDs (or revision IDs, + * depending on the $age parameter) to add each field to. + * @param $options + * An associative array of additional options, with the following keys: + * - 'deleted': If TRUE, deleted fields should be loaded as well as + * non-deleted fields. If unset or FALSE, only non-deleted fields should be + * loaded. */ -function hook_field_storage_load($entity_type, $entities, $age, $fields) { +function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) { } /** @@ -1346,25 +1351,32 @@ function hook_field_storage_delete_instance($instance) { * * This lets 3rd party modules override, mirror, shard, or otherwise store a * subset of fields in a different way than the current storage engine. - * Possible use cases include: per-bundle storage, per-combo-field storage... + * Possible use cases include per-bundle storage, per-combo-field storage, etc. + * + * Modules implementing this hook should load field values and add them to + * objects in $entities. Fields with no values should be added as empty + * arrays. In addition, fields loaded should be added as keys to $skip_fields. * * @param $entity_type - * The type of entity for which to load fields; e.g. 'node' or 'user'. + * The type of entity, such as 'node' or 'user'. * @param $entities - * An array of entities for which to load fields, keyed by entity id. + * The array of entity objects to add fields to, keyed by entity ID. * @param $age * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or * FIELD_LOAD_REVISION to load the version indicated by each entity. * @param $skip_fields - * An array keyed by field ids whose data has already been loaded and - * therefore should not be loaded again. The values associated to these keys - * are not specified. - * @return - * - Loaded field values are added to $entities. Fields with no values should - * be set as an empty array. - * - Loaded field ids are set as keys in $skip_fields. - */ -function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields) { + * An array keyed by field IDs whose data has already been loaded and + * therefore should not be loaded again. Add a key to this array to indicate + * that your module has already loaded a field. + * @param $options + * An associative array of additional options, with the following keys: + * - 'field_id': The field ID that should be loaded. If unset, all fields + * should be loaded. + * - 'deleted': If TRUE, deleted fields should be loaded as well as + * non-deleted fields. If unset or FALSE, only non-deleted fields should be + * loaded. + */ +function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) { } /** diff --git a/modules/field/field.attach.inc b/modules/field/field.attach.inc index 2a5278e1f..01bfa4c82 100644 --- a/modules/field/field.attach.inc +++ b/modules/field/field.attach.inc @@ -553,15 +553,18 @@ function field_attach_form($entity_type, $entity, &$form, &$form_state, $langcod } /** - * Load all fields for the most current version of each of a set of - * entities of a single entity type. + * Loads fields for the current revisions of a group of entities. + * + * Loads all fields for each entity object in a group of a single entity type. + * The loaded field values are added directly to the entity objects. * * @param $entity_type - * The type of $entity; e.g. 'node' or 'user'. + * The type of $entity; e.g., 'node' or 'user'. * @param $entities - * An array of entities for which to load fields, keyed by entity id. + * An array of entities for which to load fields, keyed by entity ID. * Each entity needs to have its 'bundle', 'id' and (if applicable) - * 'revision' keys filled. + * 'revision' keys filled in. The function adds the loaded field data + * directly in the entity objects of the $entities array. * @param $age * FIELD_LOAD_CURRENT to load the most recent revision for all * fields, or FIELD_LOAD_REVISION to load the version indicated by @@ -569,15 +572,13 @@ function field_attach_form($entity_type, $entity, &$form, &$form_state, $langcod * field_attach_load_revision() instead of passing FIELD_LOAD_REVISION. * @param $options * An associative array of additional options, with the following keys: - * - 'field_id': The field id that should be loaded, instead of - * loading all fields, for each entity. Note that returned entities - * may contain data for other fields, for example if they are read - * from a cache. - * - 'deleted': If TRUE, the function will operate on deleted fields - * as well as non-deleted fields. If unset or FALSE, only - * non-deleted fields are operated on. - * @return - * Loaded field values are added to $entities. + * - 'field_id': The field ID that should be loaded, instead of + * loading all fields, for each entity. Note that returned entities + * may contain data for other fields, for example if they are read + * from a cache. + * - 'deleted': If TRUE, the function will operate on deleted fields + * as well as non-deleted fields. If unset or FALSE, only + * non-deleted fields are operated on. */ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $options = array()) { $load_current = $age == FIELD_LOAD_CURRENT; @@ -693,27 +694,21 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $ } /** - * Load all fields for a previous version of each of a set of - * entities of a single entity type. + * Load all fields for previous versions of a group of entities. * - * Loading different versions of the same entities is not supported, - * and should be done by separate calls to the function. + * Loading different versions of the same entities is not supported, and should + * be done by separate calls to the function. * * @param $entity_type * The type of $entity; e.g. 'node' or 'user'. * @param $entities - * An array of entities for which to load fields, keyed by entity id. - * Each entity needs to have its 'bundle', 'id' and (if applicable) - * 'revision' keys filled. + * An array of entities for which to load fields, keyed by entity ID. Each + * entity needs to have its 'bundle', 'id' and (if applicable) 'revision' + * keys filled. The function adds the loaded field data directly in the + * entity objects of the $entities array. * @param $options - * An associative array of additional options, with the following keys: - * - 'field_name': The field name that should be loaded, instead of - * loading all fields, for each entity. Note that returned entities - * may contain data for other fields, for example if they are read - * from a cache. - * @return - * On return, the entities in $entities are modified by having the - * appropriate set of fields added. + * An associative array of additional options. See field_attach_load() for + * details. */ function field_attach_load_revision($entity_type, $entities, $options = array()) { return field_attach_load($entity_type, $entities, FIELD_LOAD_REVISION, $options); |