diff options
Diffstat (limited to 'modules/field/field.api.php')
| -rw-r--r-- | modules/field/field.api.php | 61 |
1 files changed, 39 insertions, 22 deletions
diff --git a/modules/field/field.api.php b/modules/field/field.api.php index 7971899b8..130562858 100644 --- a/modules/field/field.api.php +++ b/modules/field/field.api.php @@ -188,18 +188,32 @@ function hook_field_formatter_info() { /** * Define custom load behavior for this module's field types. * + * Unlike other field hooks, this hook operates on multiple objects. The + * $objects, $instances and $items parameters are arrays keyed by object id. + * For performance reasons, information for all available objects should be + * loaded in a single query where possible. + * + * Note that the changes made to the field values get cached by the + * field cache for subsequent loads. + * * @param $obj_type * The type of $object. - * @param $object - * The object for the operation. + * @param $objects + * Array of objects being loaded, keyed by object id. * @param $field * The field structure for the operation. - * @param $instance - * The instance structure for $field on $object's bundle. + * @param $instances + * Array of instance structures for $field for each object, keyed by object id. * @param $items - * $object->{$field['field_name']}, or an empty array if unset. + * Array of field values already loaded for the objects, keyed by object 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 object. + * @return + * Changes or additions to field values are done by altering the $items + * parameter by reference. */ -function hook_field_load($obj_type, $object, $field, $instance, $items) { +function hook_field_load($obj_type, $objects, $field, $instances, &$items, $age) { } /** @@ -452,23 +466,20 @@ function hook_field_attach_form($obj_type, $object, &$form, &$form_state) { * @param $obj_type * The type of objects for which to load fields; e.g. 'node' or 'user'. * @param $objects - * An array of objects for which to load fields. The keys for primary id and - * bundle name to load are identified by hook_fieldable_info for $obj_type. + * An array of objects for which to load fields, keyed by object 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 object. - * @param $additions - * An array of field data for the objects being loaded, keyed by entity id, - * field name, and item delta number. * @param $skip_fields * An array keyed by names of fields 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 $additions and loaded field names are set - * as keys in $skip_fields. + * - Loaded field values are added to $objects. Fields with no values should be + * set as an empty array. + * - Loaded field names are set as keys in $skip_fields. */ -function hook_field_attach_pre_load($obj_type, $objects, $age, &$additions, &$skip_fields) { +function hook_field_attach_pre_load($obj_type, &$objects, $age, &$skip_fields) { } /** @@ -476,10 +487,17 @@ function hook_field_attach_pre_load($obj_type, $objects, $age, &$additions, &$sk * * This hook is invoked after the field module has performed the operation. * + * Unlike other field_attach hooks, this hook accounts for 'multiple loads'. + * It takes an array of objects indexed by object id as its first parameter. + * For performance reasons, information for all available objects should be + * loaded in a single query where possible. + * + * Note that the changes made to the objects' field values get cached by the + * field cache for subsequent loads. + * * See field_attach_load() for details and arguments. - * TODO: Currently, this hook only accepts a single object a time. */ -function hook_field_attach_load($obj_type, $object) { +function hook_field_attach_load($obj_type, &$objects, $age) { } /** @@ -640,10 +658,9 @@ function hook_field_attach_delete_bundle($bundle, $instances) { * Load field data for a set of objects. * * @param $obj_type - * The entity type of objects being loaded, such as 'node' or - * 'user'. + * The entity type of object, such as 'node' or 'user'. * @param $objects - * The array of objects for which to load data. + * The array of objects for which to load data, keyed by object 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 @@ -653,10 +670,10 @@ function hook_field_attach_delete_bundle($bundle, $instances) { * therefore should not be loaded again. The values associated to these keys * are not specified. * @return - * An array of field data for the objects, keyed by entity id, field - * name, and item delta number. + * Loaded field values are added to $objects. Fields with no values should be + * set as an empty array. */ -function hook_field_storage_load($obj_type, $queried_objs, $age, $skip_fields) { +function hook_field_storage_load($obj_type, &$objects, $age, $skip_fields) { } /** |