diff options
| -rw-r--r-- | modules/field/field.attach.inc | 93 | ||||
| -rw-r--r-- | modules/system/system.api.php | 31 |
2 files changed, 69 insertions, 55 deletions
diff --git a/modules/field/field.attach.inc b/modules/field/field.attach.inc index 01bfa4c82..28a75fe90 100644 --- a/modules/field/field.attach.inc +++ b/modules/field/field.attach.inc @@ -80,46 +80,53 @@ define('FIELD_STORAGE_INSERT', 'insert'); * @{ * Operate on Field API data attached to Drupal entities. * - * Field Attach API functions load, store, generate Form API - * structures, display, and perform a variety of other functions for - * field data connected to individual entities. - * - * Field Attach API functions generally take $entity_type and $entity - * arguments along with additional function-specific arguments. - * $entity_type is the type of the fieldable entity, such as 'node' or - * 'user', and $entity is the entity itself. An individual entity's - * bundle, if any, is read from the entity's bundle key property - * identified by hook_fieldable_info() for $entity_type. - * - * Fieldable types call Field Attach API functions during their own - * API calls; for example, node_load() calls field_attach_load(). A - * fieldable type is not required to use all of the Field Attach - * API functions. - * - * Most Field Attach API functions define a corresponding hook - * function that allows any module to act on Field Attach operations - * for any entity after the operation is complete, and access or - * modify all the field, form, or display data for that entity and - * operation. For example, field_attach_view() invokes + * Field Attach API functions load, store, display, generate Form API + * structures, and perform a variety of other functions for field data attached + * to individual entities. + * + * Field Attach API functions generally take $entity_type and $entity arguments + * along with additional function-specific arguments. $entity_type is the type + * of the fieldable entity, such as 'node' or 'user', and $entity is the entity + * itself. + * + * hook_entity_info() is the central place for entity types to define if and + * how Field API should operate on their entity objects. Notably, the + * 'fieldable' property needs to be set to TRUE. + * + * The Field Attach API uses the concept of bundles: the set of fields for a + * given entity is defined on a per-bundle basis. The collection of bundles for + * an entity type is defined its hook_entity_info() implementation. For + * instance, node_entity_info() exposes each node type as its own bundle. This + * means that the set of fields of a node is determined by the node type. The + * Field API reads the bundle name for a given entity from a particular + * property of the entity object, and hook_entity_info() defines which property + * to use. For instance, node_entity_info() specifies: + * @code $info['entity keys']['bundle'] = 'type'@endcode + * This indicates that for a particular node object, the bundle name can be + * found in $node->type. This property can be omitted if the entity type only + * exposes a single bundle (all entities of this type have the same collection + * of fields). This is the case for the 'user' entity type. + * + * Most Field Attach API functions define a corresponding hook function that + * allows any module to act on Field Attach operations for any entity after the + * operation is complete, and access or modify all the field, form, or display + * data for that entity and operation. For example, field_attach_view() invokes * hook_field_attach_view_alter(). These all-module hooks are distinct from - * those of the Field Types API, such as hook_field_load(), that are - * only invoked for the module that defines a specific field type. - * - * field_attach_load(), field_attach_insert(), and - * field_attach_update() also define pre-operation hooks, - * e.g. hook_field_attach_pre_load(). These hooks run before the - * corresponding Field Storage API and Field Type API operations. - * They allow modules to define additional storage locations - * (e.g. denormalizing, mirroring) for field data on a per-field - * basis. They also allow modules to take over field storage - * completely by instructing other implementations of the same hook - * and the Field Storage API itself not to operate on specified - * fields. - * - * The pre-operation hooks do not make the Field Storage API - * irrelevant. The Field Storage API is essentially the "fallback - * mechanism" for any fields that aren't being intercepted explicitly - * by pre-operation hooks. + * those of the Field Types API, such as hook_field_load(), that are only + * invoked for the module that defines a specific field type. + * + * field_attach_load(), field_attach_insert(), and field_attach_update() also + * define pre-operation hooks, e.g. hook_field_attach_pre_load(). These hooks + * run before the corresponding Field Storage API and Field Type API + * operations. They allow modules to define additional storage locations (e.g. + * denormalizing, mirroring) for field data on a per-field basis. They also + * allow modules to take over field storage completely by instructing other + * implementations of the same hook and the Field Storage API itself not to + * operate on specified fields. + * + * The pre-operation hooks do not make the Field Storage API irrelevant. The + * Field Storage API is essentially the "fallback mechanism" for any fields + * that aren't being intercepted explicitly by pre-operation hooks. */ /** @@ -516,6 +523,10 @@ function _field_invoke_get_instances($entity_type, $bundle, $options) { * ), * @endcode * + * field_attach_load() is automatically called by the default entity controller + * class, and thus, in most cases, doesn't need to be explicitly called by the + * entity type module. + * * @param $entity_type * The type of $entity; e.g. 'node' or 'user'. * @param $entity @@ -699,6 +710,10 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $ * Loading different versions of the same entities is not supported, and should * be done by separate calls to the function. * + * field_attach_load_revision() is automatically called by the default entity + * controller class, and thus, in most cases, doesn't need to be explicitly + * called by the entity type module. + * * @param $entity_type * The type of $entity; e.g. 'node' or 'user'. * @param $entities diff --git a/modules/system/system.api.php b/modules/system/system.api.php index b0f58b1fe..52487ab78 100644 --- a/modules/system/system.api.php +++ b/modules/system/system.api.php @@ -77,28 +77,27 @@ function hook_hook_info() { * - entity keys: An array describing how the Field API can extract the * information it needs from the objects of the type. Elements: * - id: The name of the property that contains the primary id of the - * object. Every object passed to the Field API must have this property - * and its value must be numeric. + * entity. Every entity object passed to the Field API must have this + * property and its value must be numeric. * - revision: The name of the property that contains the revision id of - * the object. The Field API assumes that all revision ids are unique - * across all objects of a type. - * This element can be omitted if the objects of this type are not - * versionable. + * the entity. The Field API assumes that all revision ids are unique + * across all entities of a type. This entry can be omitted if the + * entities of this type are not versionable. * - bundle: The name of the property that contains the bundle name for the - * object. The bundle name defines which set of fields are attached to - * the object (e.g. what nodes call "content type"). - * This element can be omitted if this type has no bundles (all objects - * have the same fields). + * entity. The bundle name defines which set of fields are attached to + * the entity (e.g. what nodes call "content type"). This entry can be + * omitted if this entity type exposes a single bundle (all entities have + * the same collection of fields). * - bundle keys: An array describing how the Field API can extract the * information it needs from the bundle objects for this type (e.g - * $vocabulary objects for terms; not applicable for nodes). - * This element can be omitted if this type's bundles do not exist as - * standalone objects. Elements: + * $vocabulary objects for terms; not applicable for nodes). This entry can + * be omitted if this type's bundles do not exist as standalone objects. + * Elements: * - bundle: The name of the property that contains the name of the bundle * object. - * - bundles: An array describing all bundles for this object type. - * Keys are bundles machine names, as found in the objects' 'bundle' - * property (defined in the 'entity keys' entry above). Elements: + * - bundles: An array describing all bundles for this object type. Keys are + * bundles machine names, as found in the objects' 'bundle' property + * (defined in the 'entity keys' entry above). Elements: * - label: The human-readable name of the bundle. * - admin: An array of information that allows Field UI pages to attach * themselves to the existing administration pages for the bundle. |