Skip to content

GitLab

Commit 0790cd97 authored by Jennifer Hodgdon's avatar Jennifer Hodgdon
Browse files

Issue #1326634 by xjm, NROTC_Webmaster, dellintosh, xenophyle: Fix up API docs in field module

parent 2a686840
Expand all Hide whitespace changes
Inline Side-by-side
core/modules/field/field.api.php
View file @ 0790cd97
This diff is collapsed.
core/modules/field/field.attach.inc
View file @ 0790cd97
This diff is collapsed.
core/modules/field/field.crud.inc
View file @ 0790cd97
......@@ -11,13 +11,12 @@
/**
* @defgroup field_crud Field CRUD API
* @{
* Create, update, and delete Field API fields, bundles, and instances.
* Creates, updates, and deletes Field API fields, bundles, and instances.
*
* Modules use this API, often in hook_install(), to create custom
* data structures. UI modules will use it to create a user interface.
* Modules use this API, often in hook_install(), to create custom data
* structures. UI modules will use it to create a user interface.
*
* The Field CRUD API uses
* @link field Field API data structures @endlink.
* The Field CRUD API uses @link field Field API data structures @endlink.
*
* See @link field Field API @endlink for information about the other parts of
* the Field API.
......@@ -301,16 +300,16 @@ function field_update_field($field) {
*
* Generally, you should use the field_info_field() instead.
*
* This function will not return deleted fields. Use
* field_read_fields() instead for this purpose.
* This function will not return deleted fields. Use field_read_fields() instead
* for this purpose.
*
* @param $field_name
* The field name to read.
* @param array $include_additional
* The default behavior of this function is to not return a field that
* is inactive. Setting
* $include_additional['include_inactive'] to TRUE will override this
* behavior.
* The default behavior of this function is to not return a field that is
* inactive. Setting $include_additional['include_inactive'] to TRUE will
* override this behavior.
*
* @return
* A field definition array, or FALSE.
*/
......@@ -325,15 +324,15 @@ function field_read_field($field_name, $include_additional = array()) {
* @param array $params
* An array of conditions to match against.
* @param array $include_additional
* The default behavior of this function is to not return fields that
* are inactive or have been deleted. Setting
* The default behavior of this function is to not return fields that are
* inactive or have been deleted. Setting
* $include_additional['include_inactive'] or
* $include_additional['include_deleted'] to TRUE will override this
* behavior.
* $include_additional['include_deleted'] to TRUE will override this behavior.
*
* @return
* An array of fields matching $params. If
* $include_additional['include_deleted'] is TRUE, the array is keyed
* by field id, otherwise it is keyed by field name.
* $include_additional['include_deleted'] is TRUE, the array is keyed by
* field ID, otherwise it is keyed by field name.
*/
function field_read_fields($params = array(), $include_additional = array()) {
$query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));
......@@ -509,12 +508,12 @@ function field_create_instance(&$instance) {
* Updates an instance of a field.
*
* @param $instance
* An associative array representing an instance structure. The required
* keys and values are:
* An associative array representing an instance structure. The required keys
* and values are:
* - entity_type: The type of the entity the field is attached to.
* - bundle: The bundle this field belongs to.
* - field_name: The name of an existing field.
* Read-only_id properties are assigned automatically. Any other
* Read-only ID properties are assigned automatically. Any other properties
* properties specified in $instance overwrite the existing values for
* the instance.
*
......@@ -650,9 +649,9 @@ function _field_write_instance(&$instance, $update = FALSE) {
/**
* Reads a single instance record from the database.
*
* Generally, you should use field_info_instance() instead, as it
* provides caching and allows other modules the opportunity to
* append additional formatters, widgets, and other information.
* Generally, you should use field_info_instance() instead, as it provides
* caching and allows other modules the opportunity to append additional
* formatters, widgets, and other information.
*
* @param $entity_type
* The type of entity to which the field is bound.
......@@ -661,11 +660,11 @@ function _field_write_instance(&$instance, $update = FALSE) {
* @param $bundle
* The bundle to which the field is bound.
* @param array $include_additional
* The default behavior of this function is to not return an instance that
* has been deleted, or whose field is inactive. Setting
* The default behavior of this function is to not return an instance that has
* been deleted, or whose field is inactive. Setting
* $include_additional['include_inactive'] or
* $include_additional['include_deleted'] to TRUE will override this
* behavior.
* $include_additional['include_deleted'] to TRUE will override this behavior.
*
* @return
* An instance structure, or FALSE.
*/
......@@ -678,15 +677,15 @@ function field_read_instance($entity_type, $field_name, $bundle, $include_additi
* Reads in field instances that match an array of conditions.
*
* @param $param
* An array of properties to use in selecting a field
* instance. Valid keys include any column of the
* field_config_instance table. If NULL, all instances will be returned.
* An array of properties to use in selecting a field instance. Valid keys
* include any column of the field_config_instance table. If NULL, all
* instances will be returned.
* @param $include_additional
* The default behavior of this function is to not return field
* instances that have been marked deleted, or whose field is inactive.
* Setting $include_additional['include_inactive'] or
* $include_additional['include_deleted'] to TRUE will override this
* behavior.
* The default behavior of this function is to not return field instances that
* have been marked deleted, or whose field is inactive. Setting
* $include_additional['include_inactive'] or
* $include_additional['include_deleted'] to TRUE will override this behavior.
*
* @return
* An array of instances matching the arguments.
*/
......@@ -777,7 +776,7 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
/**
* @defgroup field_purge Field API bulk data deletion
* @{
* Clean up after Field API bulk deletion operations.
* Cleans up after Field API bulk deletion operations.
*
* Field API provides functions for deleting data attached to individual
* entities as well as deleting entire fields or field instances in a single
......@@ -786,20 +785,19 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
* Deleting field data items for an entity with field_attach_delete() involves
* three separate operations:
* - Invoking the Field Type API hook_field_delete() for each field on the
* entity. The hook for each field type receives the entity and the specific
* field being deleted. A file field module might use this hook to delete
* uploaded files from the filesystem.
* - Invoking the Field Storage API hook_field_storage_delete() to remove
* data from the primary field storage. The hook implementation receives the
* entity being deleted and deletes data for all of the entity's bundle's
* fields.
* entity. The hook for each field type receives the entity and the specific
* field being deleted. A file field module might use this hook to delete
* uploaded files from the filesystem.
* - Invoking the Field Storage API hook_field_storage_delete() to remove data
* from the primary field storage. The hook implementation receives the entity
* being deleted and deletes data for all of the entity's bundle's fields.
* - Invoking the global Field Attach API hook_field_attach_delete() for all
* modules that implement it. Each hook implementation receives the entity
* being deleted and can operate on whichever subset of the entity's bundle's
* fields it chooses to.
* modules that implement it. Each hook implementation receives the entity
* being deleted and can operate on whichever subset of the entity's bundle's
* fields it chooses to.
*
* These hooks are invoked immediately when field_attach_delete() is
* called. Similar operations are performed for field_attach_delete_revision().
* These hooks are invoked immediately when field_attach_delete() is called.
* Similar operations are performed for field_attach_delete_revision().
*
* When a field, bundle, or field instance is deleted, it is not practical to
* invoke these hooks immediately on every affected entity in a single page
......@@ -807,8 +805,8 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
* appropriate field data items, instances, and/or fields are marked as deleted
* so that subsequent load or query operations will not return them. Later, a
* separate process cleans up, or "purges", the marked-as-deleted data by going
* through the three-step process described above and, finally, removing
* deleted field and instance records.
* through the three-step process described above and, finally, removing deleted
* field and instance records.
*
* Purging field data is made somewhat tricky by the fact that, while
* field_attach_delete() has a complete entity to pass to the various deletion
......@@ -820,12 +818,12 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
*
* Field API resolves this problem by using "pseudo-entities" during purge
* operations. A pseudo-entity contains only the information from the original
* entity that Field API knows about: entity type, id, revision id, and
* bundle. It also contains the field data for whichever field instance is
* currently being purged. For example, suppose that the node type 'story' used
* to contain a field called 'subtitle' but the field was deleted. If node 37
* was a story with a subtitle, the pseudo-entity passed to the purge hooks
* would look something like this:
* entity that Field API knows about: entity type, ID, revision ID, and bundle.
* It also contains the field data for whichever field instance is currently
* being purged. For example, suppose that the node type 'story' used to contain
* a field called 'subtitle' but the field was deleted. If node 37 was a story
* with a subtitle, the pseudo-entity passed to the purge hooks would look
* something like this:
*
* @code
* $entity = stdClass Object(
......@@ -907,8 +905,8 @@ function field_purge_batch($batch_size) {
/**
* Purges the field data for a single field on a single pseudo-entity.
*
* This is basically the same as field_attach_delete() except it only applies
* to a single field. The entity itself is not being deleted, and it is quite
* This is basically the same as field_attach_delete() except it only applies to
* a single field. The entity itself is not being deleted, and it is quite
* possible that other field data will remain attached to it.
*
* @param $entity_type
......@@ -939,7 +937,7 @@ function field_purge_data($entity_type, $entity, $field, $instance) {
/**
* Purges a field instance record from the database.
*
* This function assumes all data for the instance has already been purged, and
* This function assumes all data for the instance has already been purged and
* should only be called by field_purge_batch().
*
* @param $instance
......
core/modules/field/field.default.inc
View file @ 0790cd97
......@@ -25,18 +25,18 @@
* @param $field
* The field structure for the operation.
* @param $instance
* The instance structure for $field on $entity's bundle.
* The instance structure for $field in $entity's bundle.
* @param $langcode
* The language associated to $items.
* The language associated with $items.
* @param $items
* $entity->{$field['field_name']}[$langcode], or an empty array if unset.
* @param $errors
* The array of errors, keyed by field name and by value delta, that have
* already been reported for the entity. The function should add its errors
* to this array. Each error is an associative array, with the following
* keys and values:
* - 'error': an error code (should be a string, prefixed with the module name)
* - 'message': the human readable message to be displayed.
* already been reported for the entity. The function should add its errors to
* this array. Each error is an associative array, with the following keys and
* values:
* - error: An error code (should be a string, prefixed with the module name).
* - message: The human readable message to be displayed.
*/
function field_default_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
// Filter out empty values.
......@@ -54,11 +54,24 @@ function field_default_validate($entity_type, $entity, $field, $instance, $langc
}
/**
* Default field 'insert' operation.
* Inserts a default value if no $entity->$field_name entry was provided.
*
* Insert default value if no $entity->$field_name entry was provided.
* This can happen with programmatic saves, or on form-based creation where
* the current user doesn't have 'edit' permission for the field.
* the current user doesn't have 'edit' permission for the field. This is the
* default field 'insert' operation.
*
* @param $entity_type
* The type of $entity.
* @param $entity
* The entity for the operation.
* @param $field
* The field structure for the operation.
* @param $instance
* The instance structure for $field in $entity's bundle.
* @param $langcode
* The language associated with $items.
* @param $items
* An array that this function will populate with default values.
*/
function field_default_insert($entity_type, $entity, $field, $instance, $langcode, &$items) {
// _field_invoke() populates $items with an empty array if the $entity has no
......@@ -79,20 +92,20 @@ function field_default_insert($entity_type, $entity, $field, $instance, $langcod
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entities
* An array of entities being displayed, keyed by entity id.
* An array of entities being displayed, keyed by entity ID.
* @param $field
* The field structure for the operation.
* @param $instances
* Array of instance structures for $field for each entity, keyed by entity
* id.
* ID.
* @param $langcode
* The language associated to $items.
* The language associated with $items.
* @param $items
* Array of field values already loaded for the entities, keyed by entity id.
* @param $display
* Can be either:
* - the name of a view mode
* - or an array of display settings to use for display, as found in the
* - The name of a view mode
* - An array of display settings to use for display, as found in the
* 'display' entry of $instance definitions.
*/
function field_default_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $display) {
......@@ -204,15 +217,15 @@ function field_default_view($entity_type, $entity, $field, $instance, $langcode,
* @param $field
* The field structure for the operation.
* @param $instance
* The instance structure for $field on $entity's bundle.
* The instance structure for $field in $entity's bundle.
* @param $langcode
* The language the entity has to be translated in.
* The language the entity has to be translated to.
* @param $items
* $entity->{$field['field_name']}[$langcode], or an empty array if unset.
* @param $source_entity
* The source entity holding the field values to be translated.
* @param $source_langcode
* The source language from which translate.
* The source language from which to translate.
*/
function field_default_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) {
$field_name = $field['field_name'];
......
core/modules/field/field.form.inc
View file @ 0790cd97
......@@ -8,14 +8,15 @@
/**
* Returns HTML for an individual form element.
*
* Combine multiple values into a table with drag-n-drop reordering.
* TODO : convert to a template.
* Combines multiple values into a table with drag-n-drop reordering.
*
* @param $variables
* An associative array containing:
* - element: A render element representing the form element.
*
* @ingroup themeable
*
* @todo Convert to a template.
*/
function theme_field_multiple_value_form($variables) {
$element = $variables['element'];
......@@ -82,11 +83,19 @@ function theme_field_multiple_value_form($variables) {
}
/**
* #after_build callback for field elements in a form.
* After-build callback for field elements in a form.
*
* This stores the final location of the field within the form structure so that
* field_default_form_errors() can assign validation errors to the right form
* element.
*
* @param $element
* The form element.
* @param $form_state
* An associative array containing the current state of the form.
*
* This stores the final location of the field within the form structure so
* that field_default_form_errors() can assign validation errors to the right
* form element.
* @return
* The $element array that was passed in as a parameter.
*
* @see field_default_form_errors()
*/
......@@ -103,7 +112,7 @@ function field_form_element_after_build($element, &$form_state) {
}
/**
* Submit handler for the "Add another item" button of a field form.
* Form submission handler for the "Add another item" button of a field form.
*
* This handler is run regardless of whether JS is enabled or not. It makes
* changes to the form state. If the button was clicked with JS disabled, then
......@@ -129,7 +138,7 @@ function field_add_more_submit($form, &$form_state) {
}
/**
* Ajax callback in response to a new empty widget being added to the form.
* Ajax callback: Responds to a new empty widget being added to the form.
*
* This returns the new page content to replace the page content made obsolete
* by the form submission.
......@@ -174,12 +183,12 @@ function field_add_more_js($form, $form_state) {
*
* @return
* An array with the following key/data pairs:
* - field: the field definition array,
* - instance: the field instance definition array,
* - items_count: the number of widgets to display for the field,
* - array_parents: the location of the field's widgets within the $form
* - field: The field definition array.
* - instance: The field instance definition array.
* - items_count: The number of widgets to display for the field.
* - array_parents: The location of the field's widgets within the $form
* structure. This entry is populated at '#after_build' time.
* - errors: the array of field validation errors reported on the field. This
* - errors: The array of field validation errors reported on the field. This
* entry is populated at field_attach_form_validate() time.
*
* @see field_form_set_state()
......@@ -213,6 +222,16 @@ function field_form_set_state($parents, $field_name, $langcode, &$form_state, $f
/**
* Returns the location of processing information within $form_state.
*
* @param $parents
* The array of #parents where the field lives in the form.
* @param $field_name
* The field name.
* @param $langcode
* The language in which the field values are entered.
*
* @return
* The location of processing information within $form_state.
*/
function _field_form_state_parents($parents, $field_name, $langcode) {
// To ensure backwards compatibility on regular entity forms for widgets that
......@@ -238,7 +257,7 @@ function _field_form_state_parents($parents, $field_name, $langcode) {
/**
* Retrieves the field definition for a widget's helper callbacks.
*
* Widgets helper element callbacks (such as #process, #element_validate,
* Widget helper element callbacks (such as #process, #element_validate,
* #value_callback, ...) should use field_widget_field() and
* field_widget_instance() instead of field_info_field() and
* field_info_instance() when they need to access field or instance properties.
......
core/modules/field/field.info.inc
View file @ 0790cd97
......@@ -10,11 +10,11 @@
/**
* @defgroup field_info Field Info API
* @{
* Obtain information about Field API configuration.
* Obtains information about Field API configuration.
*
* The Field Info API exposes information about field types, fields,
* instances, bundles, widget types, display formatters, behaviors,
* and settings defined by or with the Field API.
* The Field Info API exposes information about field types, fields, instances,
* bundles, widget types, display formatters, behaviors, and settings defined by
* or with the Field API.
*
* See @link field Field API @endlink for information about the other parts of
* the Field API.
......@@ -23,9 +23,8 @@
/**
* Clears the field info cache without clearing the field data cache.
*
* This is useful when deleted fields or instances are purged. We
* need to remove the purged records, but no actual field data items
* are affected.
* This is useful when deleted fields or instances are purged. We need to remove
* the purged records, but no actual field data items are affected.
*/
function field_info_cache_clear() {
drupal_static_reset('field_view_mode_settings');
......@@ -145,7 +144,7 @@ function _field_info_collate_types() {
}
/**
* Clear collated information on field and widget types and related structures.
* Clears collated information on field and widget types and related structures.
*/
function _field_info_collate_types_reset() {
drupal_static_reset('_field_info_collate_types');
......@@ -158,15 +157,15 @@ function _field_info_collate_types_reset() {
*
* @return
* An associative array containing:
* - fields: Array of existing fields, keyed by field ID. This element
* lists deleted and non-deleted fields, but not inactive ones.
* Each field has an additional element, 'bundles', which is an array
* of all non-deleted instances of that field.
* - field_ids: Array of field IDs, keyed by field name. This element
* only lists non-deleted, active fields.
* - instances: Array of existing instances, keyed by entity type, bundle
* name and field name. This element only lists non-deleted instances
* whose field is active.
* - fields: Array of existing fields, keyed by field ID. This element lists
* deleted and non-deleted fields, but not inactive ones. Each field has an
* additional element, 'bundles', which is an array of all non-deleted
* instances of that field.
* - field_ids: Array of field IDs, keyed by field name. This element only
* lists non-deleted, active fields.
* - instances: Array of existing instances, keyed by entity type, bundle name
* and field name. This element only lists non-deleted instances whose field
* is active.
*
* @see _field_info_collate_fields_reset()
*/
......@@ -240,7 +239,7 @@ function _field_info_collate_fields() {
}
/**
* Clear collated information on existing fields and instances.
* Clears collated information on existing fields and instances.
*/
function _field_info_collate_fields_reset() {
drupal_static_reset('_field_info_collate_fields');
......@@ -255,6 +254,9 @@ function _field_info_collate_fields_reset() {
*
* @param $field
* The raw field structure as read from the database.
*
* @return
* The field array with storage and settings data added.
*/
function _field_info_prepare_field($field) {
// Make sure all expected field settings are present.
......@@ -277,7 +279,7 @@ function _field_info_prepare_field($field) {
*
* Since the instance was last saved or updated, a number of things might have
* changed: widgets or formatters disabled, new settings expected, new view
* modes added...
* modes added, etc.
*
* @param $instance
* The raw instance structure as read from the database.
......@@ -327,8 +329,10 @@ function _field_info_prepare_instance($instance, $field) {
* @param $field
* The field structure for the instance.
* @param $display
* Display specifications as found in
* $instance['display']['some_view_mode'].
* Display specifications as found in $instance['display']['some_view_mode'].
*
* @return
* The modified $display array.
*/
function _field_info_prepare_instance_display($field, $display) {
$field_type = field_info_field_types($field['type']);
......@@ -364,6 +368,9 @@ function _field_info_prepare_instance_display($field, $display) {
* The entity type.
* @param $bundle
* The bundle name.
*
* @return
* An array of data about extra fields.
*/
function _field_info_prepare_extra_fields($extra_fields, $entity_type, $bundle) {
$entity_type_info = entity_get_info($entity_type);
......@@ -408,8 +415,8 @@ function _field_info_prepare_extra_fields($extra_fields, $entity_type, $bundle)
* Determines the behavior of a widget with respect to an operation.
*
* @param $op
* The name of the operation. Currently supported: 'default value',
* 'multiple values'.
* The name of the operation. Currently supported: 'default value', 'multiple
* values'.
* @param $instance
* The field instance array.
*
......@@ -428,8 +435,7 @@ function field_behaviors_widget($op, $instance) {
* Returns information about field types from hook_field_info().
*
* @param $field_type
* (optional) A field type name. If omitted, all field types will be
* returned.
* (optional) A field type name. If omitted, all field types will be returned.
*
* @return
* Either a field type description, as provided by hook_field_info(), or an
......@@ -502,8 +508,8 @@ function field_info_formatter_types($formatter_type = NULL) {
*
* @return
* Either a storage type description, as provided by
* hook_field_storage_info(), or an array of all existing storage types,
* keyed by storage type name.
* hook_field_storage_info(), or an array of all existing storage types, keyed
* by storage type name.
*/
function field_info_storage_types($storage_type = NULL) {
$info = _field_info_collate_types();
......@@ -525,9 +531,9 @@ function field_info_storage_types($storage_type = NULL) {
* The type of entity; e.g. 'node' or 'user'.
*
* @return
* An array of bundles for the $entity_type keyed by bundle name,
* or, if no $entity_type was provided, the array of all existing bundles,
* keyed by entity type.
* An array of bundles for the $entity_type keyed by bundle name, or, if no
* $entity_type was provided, the array of all existing bundles, keyed by
* entity type.
*/
function field_info_bundles($entity_type = NULL) {
$info = entity_get_info();
......@@ -549,7 +555,7 @@ function field_info_bundles($entity_type = NULL) {
* @return
* An array of field definitions, keyed by field name. Each field has an
* additional property, 'bundles', which is an array of all the bundles to
* which this field belongs keyed by entity type.
* which this field belongs, keyed by entity type.
*/
function field_info_fields() {
$fields = array();
......@@ -590,13 +596,13 @@ function field_info_field($field_name) {
* Returns data about an individual field, given a field ID.
*
* @param $field_id
* The id of the field to retrieve. $field_id can refer to a
* deleted field, but not an inactive one.
* The ID of the field to retrieve. $field_id can refer to a deleted field,
* but not an inactive one.
*
* @return
* The field array, as returned by field_read_fields(), with an
* additional element 'bundles', whose value is an array of all the bundles
* this field belongs to.
* The field array, as returned by field_read_fields(), with an additional
* element 'bundles', whose value is an array of all the bundles this field
* belongs to.
*
* @see field_info_field()
*/
......@@ -637,8 +643,8 @@ function field_info_field_by_ids() {
* @return
* If $entity_type is not set, return all instances keyed by entity type and
* bundle name. If $entity_type is set, return all instances for that entity
* type, keyed by bundle name. If $entity_type and $bundle_name are set, return
* all instances for that bundle.
* type, keyed by bundle name. If $entity_type and $bundle_name are set,
* return all instances for that bundle.
*/
function field_info_instances($entity_type = NULL, $bundle_name = NULL) {
$info = _field_info_collate_fields();
......@@ -722,8 +728,8 @@ function field_info_instance($entity_type, $field_name, $bundle_name) {
* @param $bundle
* The bundle name.
* @param $context
* The context for which the list of pseudo-fields is requested. Either
* 'form' or 'display'.
* The context for which the list of pseudo-fields is requested. Either 'form'
* or 'display'.
*
* @return
* The array of pseudo-field elements in the bundle.
......@@ -749,6 +755,7 @@ function field_info_extra_fields($entity_type, $bundle, $context) {
* @param $context
* The context for which the maximum weight is requested. Either 'form', or
* the name of a view mode.
*
* @return
* The maximum weight of the entity's components, or NULL if no components
* were found.
......
core/modules/field/field.install
View file @ 0790cd97
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the field module.
* Install, update, and uninstall functions for the Field module.
*/
/**
......@@ -167,7 +167,7 @@ function field_schema() {
}
/**