Skip to content

GitLab

D
drupal
Commit 0790cd97 authored by jhodgdon's avatar jhodgdon
Browse files
Options

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

parent 2a686840
Expand all Show whitespace changes
Inline Side-by-side
Showing with 792 additions and 628 deletions
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
This diff is collapsed.
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() {
}
/**
* Utility function: create a field by writing directly to the database.
* Creates a field by writing directly to the database.
*
* @ingroup update-api-7.x-to-8.x
*/
......@@ -237,7 +237,7 @@ function _update_7000_field_create_field(&$field) {
}
/**
* Utility function: delete a field stored in SQL storage directly from the database.
* Deletes a field stored in SQL storage directly from the database.
*
* To protect user data, this function can only be used to delete fields once
* all information it stored is gone. Delete all data from the
......@@ -272,9 +272,9 @@ function _update_7000_field_delete_field($field_name) {
/**
* Utility function: delete an instance and all its data of a field stored in SQL Storage.
* Deletes an instance and all its data of a field stored in SQL Storage.
*
* BEWARE: this function deletes user data from the field storage tables.
* BEWARE: This function deletes user data from the field storage tables.
*
* @ingroup update-api-7.x-to-8.x
*/
......@@ -298,9 +298,9 @@ function _update_7000_field_delete_instance($field_name, $entity_type, $bundle)
}
/**
* Utility function: fetch all the field definitions from the database.
* Fetches all of the field definitions from the database.
*
* Warning: unlike the field_read_fields() API function, this function returns
* Warning: Unlike the field_read_fields() API function, this function returns
* all fields by default, including deleted and inactive fields, unless
* specified otherwise in the $conditions parameter.
*
......@@ -344,7 +344,7 @@ function _update_7000_field_read_fields(array $conditions = array(), $key = 'id'
}
/**
* Utility function: write a field instance directly to the database.
* Writes a field instance directly to the database.
*
* @ingroup update-api-7.x-to-8.x
*/
......
core/modules/field/field.module
View file @ 0790cd97
This diff is collapsed.
core/modules/field/field.multilingual.inc
View file @ 0790cd97
......@@ -8,7 +8,7 @@
/**
* @defgroup field_language Field Language API
* @{
* Handling of multilingual fields.
* Handles multilingual fields.
*
* Fields natively implement multilingual support, and all fields use the
* following structure:
......@@ -32,10 +32,16 @@
* module registering itself via hook_entity_info() to handle field
* translations.
*
* By default, _field_invoke() and _field_invoke_multiple() are processing a
* field in all available languages, unless they are given a language code
* suggestion. Based on that suggestion, _field_language_suggestion() determines
* the languages to act on.
* By default, _field_invoke() and _field_invoke_multiple() process a field in
* all available languages, unless they are given a language code suggestion.
* Based on that suggestion, _field_language_suggestion() determines the
* languages to act on.
*
* Most field_attach_*() functions act on all available language codes, except
* for the following:
......@@ -142,8 +148,7 @@ function field_available_languages($entity_type, $field) {
}
/**
* Process the given language code suggestion based on the available language
* codes.
* Process the language code suggestion based on the available language codes.
*
* If a non-empty language code suggestion is provided it must appear among the
* available language codes, otherwise it will be ignored.
......@@ -207,8 +212,8 @@ function field_is_translatable($entity_type, $field) {
/**
* Checks if a module is registered as a translation handler for a given entity.
*
* If no handler is passed, simply check if there is any translation handler
* enabled for the given entity type.
* If no handler is passed, the function simply checks if there is any
* translation handler enabled for the given entity type.
*
* @param $entity_type
* The type of the entity whose fields are to be translated.
......@@ -250,6 +255,7 @@ function field_has_translation_handler($entity_type, $handler = NULL) {
* @param $default
* Whether to return the default language code or the current language code in
* case $langcode is invalid.
*
* @return
* A valid language code.
*/
......
core/modules/field/modules/field_sql_storage/field_sql_storage.install
View file @ 0790cd97
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the field_sql_storage module.
* Install, update, and uninstall functions for the Field SQL Storage module.
*/
/**
......@@ -25,7 +25,7 @@ function field_sql_storage_schema() {
}
/**
* Utility function: write field data directly to SQL storage.
* Writes field data directly to SQL storage.
*
* @ingroup update-api-7.x-to-8.x
*/
......
core/modules/field/modules/field_sql_storage/field_sql_storage.module
View file @ 0790cd97
......@@ -37,12 +37,13 @@ function field_sql_storage_field_storage_info() {
}
/**
* Generate a table name for a field data table.
* Generates a table name for a field data table.
*
* @param $field
* The field structure.
*
* @return
* A string containing the generated name for the database table
* A string containing the generated name for the database table.
*/
function _field_sql_storage_tablename($field) {
if ($field['deleted']) {
......@@ -54,12 +55,13 @@ function _field_sql_storage_tablename($field) {
}
/**
* Generate a table name for a field revision archive table.
* Generates a table name for a field revision archive table.
*
* @param $name
* The field structure.
*
* @return
* A string containing the generated name for the database table
* A string containing the generated name for the database table.
*/
function _field_sql_storage_revision_tablename($field) {
if ($field['deleted']) {
......@@ -71,40 +73,43 @@ function _field_sql_storage_revision_tablename($field) {
}
/**
* Generate a column name for a field data table.
* Generates a column name for a field data table.
*
* @param $name
* The name of the field
* The name of the field.
* @param $column
* The name of the column
* The name of the column.
*
* @return
* A string containing a generated column name for a field data
* table that is unique among all other fields.
* A string containing a generated column name for a field data table that is
* unique among all other fields.
*/
function _field_sql_storage_columnname($name, $column) {
return $name . '_' . $column;
}
/**
* Generate an index name for a field data table.
* Generates an index name for a field data table.
*
* @param $name
* The name of the field
* The name of the field.
* @param $column
* The name of the index
* The name of the index.
*
* @return
* A string containing a generated index name for a field data
* table that is unique among all other fields.
* A string containing a generated index name for a field data table that is
* unique among all other fields.
*/
function _field_sql_storage_indexname($name, $index) {
return $name . '_' . $index;
}
/**
* Return the database schema for a field. This may contain one or
* more tables. Each table will contain the columns relevant for the
* specified field. Leave the $field's 'columns' and 'indexes' keys
* empty to get only the base schema.
* Returns the database schema for a field.
*
* This may contain one or more tables. Each table will contain the columns
* relevant for the specified field. Leave the $field's 'columns' and 'indexes'
* keys empty to get only the base schema.
*
* @param $field
* The field structure for which to generate a database schema.
......@@ -227,8 +232,8 @@ function field_sql_storage_field_storage_create_field($field) {
/**
* Implements hook_field_update_forbid().
*
* Forbid any field update that changes column definitions if there is
* any data.
* Forbids any field update that changes column definitions if there is any
* data.
*/
function field_sql_storage_field_update_forbid($field, $prior_field, $has_data) {
if ($has_data && $field['columns'] != $prior_field['columns']) {
......@@ -633,11 +638,11 @@ function field_sql_storage_field_storage_query(EntityFieldQuery $query) {
* @param $entity_type
* The entity type for which the base table should be joined.
* @param $field_base_table
* Name of a table in $select_query. As only INNER JOINs are used, it does
* not matter which.
* Name of a table in $select_query. As only INNER JOINs are used, it does not
* matter which.
*
* @return
* The name of the entity base table joined in.
* The name of the entity base table that was joined in.
*/
function _field_sql_storage_query_join_entity(Select $select_query, $entity_type, $field_base_table) {
$entity_info = entity_get_info($entity_type);
......@@ -754,8 +759,8 @@ function field_sql_storage_field_attach_rename_bundle($entity_type, $bundle_old,
/**
* Implements hook_field_storage_purge_field().
*
* All field data items and instances have already been purged, so all
* that is left is to delete the table.
* All field data items and instances have already been purged, so all that is
* left is to delete the table.
*/
function field_sql_storage_field_storage_purge_field($field) {
$table_name = _field_sql_storage_tablename($field);
......
core/modules/field/modules/number/number.install
View file @ 0790cd97
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the number module.
* Install, update, and uninstall functions for the Number module.
*/
/**
......
core/modules/field/modules/number/number.module
View file @ 0790cd97
......@@ -119,8 +119,8 @@ function number_field_instance_settings_form($field, $instance) {
* Implements hook_field_validate().
*
* Possible error codes:
* - 'number_min': The value is less than the allowed minimum value.
* - 'number_max': The value is greater than the allowed maximum value.
* - number_min: The value is less than the allowed minimum value.
* - number_max: The value is greater than the allowed maximum value.
*/
function number_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
foreach ($items as $delta => $item) {
......
core/modules/field/modules/options/options.module
View file @ 0790cd97
......@@ -561,7 +561,7 @@ function options_field_widget_settings_form($field, $instance) {
}
/**
* Form element validation handler for options element.
* Form element validation handler for options elements.
*/
function options_field_widget_validate($element, &$form_state) {
if ($element['#required'] && $element['#value'] == '_none') {
......@@ -575,6 +575,18 @@ function options_field_widget_validate($element, &$form_state) {
/**
* Describes the preparation steps required by each widget.
*
* @param $type
* The type of widget: select, buttons, or onoff.