Commit 6c049009 authored by Dries's avatar Dries

- Patch #584130 by jhodgdon, yched: field Attach API page has outdated information.

parent a9d7d546
......@@ -80,46 +80,53 @@ class FieldQueryException extends FieldException {}
* @{
* 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
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment