Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

8.0.x
Jennifer Hodgdon 2012-09-27 08:44:17 -07:00
parent 2a68684092
commit 0790cd975b
16 changed files with 782 additions and 618 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
core/modules/field/field.api.php
View File

@ -17,16 +17,16 @@ use Drupal\field\FieldUpdateForbiddenException;
*
* Fieldable entities or modules that want to have their components supported
* should expose them using this hook. The user-defined settings (weight,
* visible) are automatically applied on rendered forms and displayed
* entities in a #pre_render callback added by field_attach_form() and
* visible) are automatically applied on rendered forms and displayed entities
* in a #pre_render callback added by field_attach_form() and
* field_attach_view().
*
* @see _field_extra_fields_pre_render()
* @see hook_field_extra_fields_alter()
*
* @return
* A nested array of 'pseudo-field' components. Each list is nested within
* the following keys: entity type, bundle name, context (either 'form' or
* A nested array of 'pseudo-field' components. Each list is nested within the
* following keys: entity type, bundle name, context (either 'form' or
* 'display'). The keys are the name of the elements as appearing in the
* renderable array (either the entity form or the displayed entity). The
* value is an associative array:
@ -87,7 +87,7 @@ function hook_field_extra_fields_alter(&$info) {
/**
* @defgroup field_types Field Types API
* @{
* Define field types.
* Defines field, widget, display formatter, and storage types.
*
* In the Field API, each field has a type, which determines what kind of data
* (integer, string, date, etc.) the field can hold, which settings it provides,
@ -101,7 +101,7 @@ function hook_field_extra_fields_alter(&$info) {
* appears in edit forms, while @link field_formatter formatters @endlink
* specify how the field appears in displayed entities.
*
* A third kind of pluggable handlers, storage backends, is defined by the
* A third kind of pluggable handler, storage backends, is defined by the
* @link field_storage Field Storage API @endlink.
*
* See @link field Field API @endlink for information about the other parts of
@ -128,10 +128,10 @@ function hook_field_extra_fields_alter(&$info) {
* acting on the schema definition, or settings that Views needs to use
* across field instances (for example, the list of allowed values).
* - default_widget: The machine name of the default widget to be used by
* instances of this field type, when no widget is specified in the
* instance definition. This widget must be available whenever the field
* type is available (i.e. provided by the field type module, or by a module
* the field type module depends on).
* instances of this field type, when no widget is specified in the instance
* definition. This widget must be available whenever the field type is
* available (i.e. provided by the field type module, or by a module the
* field type module depends on).
* - default_formatter: The machine name of the default formatter to be used
* by instances of this field type, when no formatter is specified in the
* instance definition. This formatter must be available whenever the field
@ -213,14 +213,13 @@ function hook_field_info_alter(&$info) {
* settings when possible. No assumptions should be made on how storage
* engines internally use the original column name to structure their
* storage.
* - indexes: (optional) An array of Schema API indexes definitions. Only
* - indexes: (optional) An array of Schema API index definitions. Only
* columns that appear in the 'columns' array are allowed. Those indexes
* will be used as default indexes. Callers of field_create_field() can
* specify additional indexes, or, at their own risk, modify the default
* specify additional indexes or, at their own risk, modify the default
* indexes specified by the field-type module. Some storage engines might
* not support indexes.
* - foreign keys: (optional) An array of Schema API foreign keys
* definitions.
* - foreign keys: (optional) An array of Schema API foreign key definitions.
*/
function hook_field_schema($field) {
if ($field['type'] == 'text_long') {
@ -317,8 +316,8 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
/**
* Prepare field values prior to display.
*
* This hook is invoked before the field values are handed to formatters
* for display, and runs before the formatters' own
* This hook is invoked before the field values are handed to formatters for
* display, and runs before the formatters' own
* hook_field_formatter_prepare_view().
*
* Unlike most other field hooks, this hook operates on multiple entities. The
@ -339,7 +338,7 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
* Array of instance structures for $field for each entity, keyed by entity
* ID.
* @param $langcode
* The language associated to $items.
* The language associated with $items.
* @param $items
* $entity->{$field['field_name']}, or an empty array if unset.
*/
@ -383,7 +382,7 @@ function hook_field_prepare_view($entity_type, $entities, $field, $instances, $l
* 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.
* - message: The human-readable message to be displayed.
*/
function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
foreach ($items as $delta => $item) {
@ -600,9 +599,9 @@ function hook_field_delete($entity_type, $entity, $field, $instance, $langcode,
/**
* Define custom revision delete behavior for this module's field types.
*
* This hook is invoked just before the data is deleted from field storage
* in field_attach_delete_revision(), and will only be called for fieldable
* types that are versioned.
* This hook is invoked just before the data is deleted from field storage in
* field_attach_delete_revision(), and will only be called for fieldable types
* that are versioned.
*
* @param $entity_type
* The type of $entity.
@ -639,7 +638,7 @@ function hook_field_delete_revision($entity_type, $entity, $field, $instance, $l
* @param $instance
* The instance structure for $field on $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 $source_entity
@ -667,8 +666,8 @@ function hook_field_prepare_translation($entity_type, $entity, $field, $instance
* The field to which $item belongs.
*
* @return
* TRUE if $field's type considers $item not to contain any data;
* FALSE otherwise.
* TRUE if $field's type considers $item not to contain any data; FALSE
* otherwise.
*/
function hook_field_is_empty($item, $field) {
if (empty($item['value']) && (string) $item['value'] !== '0') {
@ -853,17 +852,17 @@ function hook_field_widget_properties_alter(array &$widget_properties, array $co
* field_attach_view() functions.
*
* @return
* An array describing the formatter types implemented by the module.
* The keys are formatter type names. To avoid name clashes, formatter type
* names should be prefixed with the name of the module that exposes them.
* The values are arrays describing the formatter type, with the following
* An array describing the formatter types implemented by the module. The keys
* are formatter type names. To avoid name clashes, formatter type names
* should be prefixed with the name of the module that exposes them. The
* values are arrays describing the formatter type, with the following
* key/value pairs:
* - label: The human-readable name of the formatter type.
* - description: A short description for the formatter type.
* - description: A short description of the formatter type.
* - field types: An array of field types the formatter supports.
* - settings: An array whose keys are the names of the settings available
* for the formatter type, and whose values are the default values for
* those settings.
* - settings: An array whose keys are the names of the settings available to
* the formatter type, and whose values are the default values for those
* settings.
*
* @see hook_field_formatter_info_alter()
* @see hook_field_formatter_view()
@ -923,7 +922,7 @@ function hook_field_formatter_info_alter(&$info) {
*
* This should be used when a formatter needs to load additional information
* from the database in order to render a field, for example a reference field
* which displays properties of the referenced entities such as name or type.
* that displays properties of the referenced entities such as name or type.
*
* This hook is called after the field type's own hook_field_prepare_view().
*
@ -932,6 +931,9 @@ function hook_field_formatter_info_alter(&$info) {
* For performance reasons, information for all available entities should be
* loaded in a single query where possible.
*
* Changes or additions to field values are done by alterings the $items
* parameter by reference.
*
* @param $entity_type
* The type of $entity.
* @param $entities
@ -948,10 +950,6 @@ function hook_field_formatter_info_alter(&$info) {
* Array of field values for the entities, keyed by entity ID.
* @param $displays
* Array of display settings to use for each entity, keyed by entity ID.
*
* @return
* Changes or additions to field values are done by altering the $items
* parameter by reference.
*/
function hook_field_formatter_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $displays) {
$tids = array();
@ -1010,13 +1008,13 @@ function hook_field_formatter_prepare_view($entity_type, $entities, $field, $ins
* Array of values for this field.
* @param $display
* The display settings to use, as found in the 'display' entry of instance
* definitions. The array notably contains the following keys and values;
* definitions. The array notably contains the following keys and values:
* - type: The name of the formatter to use.
* - settings: The array of formatter settings.
*
* @return
* A renderable array for the $items, as an array of child elements keyed
* by numeric indexes starting from 0.
* A renderable array for $items, as an array of child elements keyed by
* numeric indexes starting from 0.
*/
function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
$element = array();
@ -1082,18 +1080,18 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
* @param $entity
* The entity for which an edit form is being built.
* @param $form
* The form structure where field elements are attached to. This might be a
* full form structure, or a sub-element of a larger form. The
* $form['#parents'] property can be used to identify the corresponding part
* of $form_state['values']. Hook implementations that need to act on the
* The form structure field elements are attached to. This might be a full
* form structure, or a sub-element of a larger form. The $form['#parents']
* property can be used to identify the corresponding part of
* $form_state['values']. Hook implementations that need to act on the
* top-level properties of the global form (like #submit, #validate...) can
* add a #process callback to the array received in the $form parameter, and
* act on the $complete_form parameter in the process callback.
* @param $form_state
* An associative array containing the current state of the form.
* @param $langcode
* The language the field values are going to be entered in. If no language
* is provided the default site language will be used.
* The language the field values are going to be entered in. If no language is
* provided the default site language will be used.
*/
function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) {
// Add a checkbox allowing a given field to be emptied.
@ -1128,7 +1126,17 @@ function hook_field_attach_load($entity_type, $entities, $age, $options) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_validate() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* The entity with fields to validate.
* @param $errors
* The array of errors (keyed by field name, language code, and 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.
*/
function hook_field_attach_validate($entity_type, $entity, &$errors) {
// @todo Needs function body.
@ -1145,8 +1153,8 @@ function hook_field_attach_validate($entity_type, $entity, &$errors) {
* The entity for which an edit form is being submitted. The incoming form
* values have been extracted as field values of the $entity object.
* @param $form
* The form structure where field elements are attached to. This might be a
* full form structure, or a sub-part of a larger form. The $form['#parents']
* The form structure field elements are attached to. This might be a full
* form structure, or a sub-part of a larger form. The $form['#parents']
* property can be used to identify the corresponding part of
* $form_state['values'].
* @param $form_state
@ -1166,7 +1174,10 @@ function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_presave() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_presave($entity_type, $entity) {
// @todo Needs function body.
@ -1177,7 +1188,10 @@ function hook_field_attach_presave($entity_type, $entity) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_insert() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_insert($entity_type, $entity) {
// @todo Needs function body.
@ -1188,7 +1202,10 @@ function hook_field_attach_insert($entity_type, $entity) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_update() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_update($entity_type, $entity) {
// @todo Needs function body.
@ -1197,8 +1214,8 @@ function hook_field_attach_update($entity_type, $entity) {
/**
* Alter field_attach_preprocess() variables.
*
* This hook is invoked while preprocessing the field.tpl.php template file
* in field_attach_preprocess().
* This hook is invoked while preprocessing the field.tpl.php template file in
* field_attach_preprocess().
*
* @param $variables
* The variables array is passed by reference and will be populated with field
@ -1218,7 +1235,10 @@ function hook_field_attach_preprocess_alter(&$variables, $context) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_delete() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_delete($entity_type, $entity) {
// @todo Needs function body.
@ -1229,7 +1249,10 @@ function hook_field_attach_delete($entity_type, $entity) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_delete_revision() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_delete_revision($entity_type, $entity) {
// @todo Needs function body.
@ -1240,8 +1263,8 @@ function hook_field_attach_delete_revision($entity_type, $entity) {
*
* This hook is invoked in field_purge_data() and allows modules to act on
* purging data from a single field pseudo-entity. For example, if a module
* relates data in the field with its own data, it may purge its own data
* during this process as well.
* relates data in the field with its own data, it may purge its own data during
* this process as well.
*
* @param $entity_type
* The type of $entity; for example, 'node' or 'user'.
@ -1277,9 +1300,9 @@ function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
* - display: Either a view mode string or an array of display settings. If
* this hook is being invoked from field_attach_view(), the 'display'
* element is set to the view mode string. If this hook is being invoked
* from field_view_field(), this element is set to the $display argument
* and the view_mode element is set to '_custom'. See field_view_field()
* for more information on what its $display argument contains.
* from field_view_field(), this element is set to the $display argument and
* the view_mode element is set to '_custom'. See field_view_field() for
* more information on what its $display argument contains.
* - language: The language code used for rendering.
*/
function hook_field_attach_view_alter(&$output, $context) {
@ -1310,9 +1333,9 @@ function hook_field_attach_view_alter(&$output, $context) {
* @param $context
* An associative array containing:
* - entity_type: The type of $entity; e.g. 'node' or 'user'.
* - langcode: The language the entity has to be translated in.
* - langcode: The language the entity will be translated to.
* - source_entity: The entity holding the field values to be translated.
* - source_langcode: The source language from which translate.
* - source_langcode: The source language from which to translate.
*/
function hook_field_attach_prepare_translation_alter(&$entity, $context) {
if ($context['entity_type'] == 'custom_entity_type') {
@ -1369,7 +1392,10 @@ function hook_field_available_languages_alter(&$langcodes, $context) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_create_bundle() for details and arguments.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* @param $entity
* the entity with fields to process.
*/
function hook_field_attach_create_bundle($entity_type, $bundle) {
// When a new bundle is created, the menu needs to be rebuilt to add the
@ -1382,7 +1408,12 @@ function hook_field_attach_create_bundle($entity_type, $bundle) {
*
* This hook is invoked after the field module has performed the operation.
*
* See field_attach_rename_bundle() for details and arguments.
* @param $entity_type
* The entity type to which the bundle is bound.
* @param $bundle_old
* The previous name of the bundle.
* @param $bundle_new
* The new name of the bundle.
*/
function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
// Update the extra weights variable with new information.
@ -1431,16 +1462,16 @@ function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) {
* Expose Field API storage backends.
*
* @return
* An array describing the storage backends implemented by the module.
* The keys are storage backend names. To avoid name clashes, storage backend
* names should be prefixed with the name of the module that exposes them.
* The values are arrays describing the storage backend, with the following
* An array describing the storage backends implemented by the module. The
* keys are storage backend names. To avoid name clashes, storage backend
* names should be prefixed with the name of the module that exposes them. The
* values are arrays describing the storage backend, with the following
* key/value pairs:
* - label: The human-readable name of the storage backend.
* - description: A short description for the storage backend.
* - settings: An array whose keys are the names of the settings available
* for the storage backend, and whose values are the default values for
* those settings.
* - settings: An array whose keys are the names of the settings available to
* the storage backend, and whose values are the default values of those
* settings.
*/
function hook_field_storage_info() {
return array(
@ -1473,8 +1504,8 @@ function hook_field_storage_info_alter(&$info) {
* the table. A key/value storage module might return the server name,
* authentication credentials, and bin name.
*
* Field storage modules are not obligated to implement this hook. Modules
* that rely on these details must only use them for read operations.
* Field storage modules are not obligated to implement this hook. Modules that
* rely on these details must only use them for read operations.
*
* @param $field
* A field structure.
@ -1539,12 +1570,11 @@ function hook_field_storage_details_alter(&$details, $field) {
/**
* Load field data for a set of entities.
*
* This hook is invoked from field_attach_load() to ask the field storage
* module to load field data.
* This hook is invoked from field_attach_load() to ask the field storage module
* to load field data.
*
* Modules implementing this hook should load field values and add them to
* objects in $entities. Fields with no values should be added as empty
* arrays.
* objects in $entities. Fields with no values should be added as empty arrays.
*
* @param $entity_type
* The type of entity, such as 'node' or 'user'.
@ -1559,9 +1589,8 @@ function hook_field_storage_details_alter(&$details, $field) {
* depending on the $age parameter) to add each field to.
* @param $options
* An associative array of additional options, with the following keys:
* - deleted: If TRUE, deleted fields should be loaded as well as
* non-deleted fields. If unset or FALSE, only non-deleted fields should be
* loaded.
* - deleted: If TRUE, deleted fields should be loaded as well as non-deleted
* fields. If unset or FALSE, only non-deleted fields should be loaded.
*/
function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) {
$field_info = field_info_field_by_ids();
@ -1611,8 +1640,8 @@ function hook_field_storage_load($entity_type, $entities, $age, $fields, $option
/**
* Write field data for an entity.
*
* This hook is invoked from field_attach_insert() and field_attach_update(),
* to ask the field storage module to save field data.
* This hook is invoked from field_attach_insert() and field_attach_update(), to
* ask the field storage module to save field data.
*
* @param $entity_type
* The entity type of entity, such as 'node' or 'user'.
@ -1883,8 +1912,8 @@ function hook_field_storage_query($query) {
* Act on creation of a new field.
*
* This hook is invoked from field_create_field() to ask the field storage
* module to save field information and prepare for storing field instances.
* If there is a problem, the field storage module should throw an exception.
* module to save field information and prepare for storing field instances. If
* there is a problem, the field storage module should throw an exception.
*
* @param $field
* The field structure being created.
@ -1955,13 +1984,13 @@ function hook_field_storage_delete_instance($instance) {
* This hook allows modules to load data before the Field Storage API,
* optionally preventing the field storage module from doing so.
*
* This lets 3rd party modules override, mirror, shard, or otherwise store a
* subset of fields in a different way than the current storage engine.
* Possible use cases include per-bundle storage, per-combo-field storage, etc.
* This lets 3rd party modules override, mirror, share, or otherwise store a
* subset of fields in a different way than the current storage engine. Possible
* use cases include per-bundle storage, per-combo-field storage, etc.
*
* Modules implementing this hook should load field values and add them to
* objects in $entities. Fields with no values should be added as empty
* arrays. In addition, fields loaded should be added as keys to $skip_fields.
* objects in $entities. Fields with no values should be added as empty arrays.
* In addition, fields loaded should be added as keys to $skip_fields.
*
* @param $entity_type
* The type of entity, such as 'node' or 'user'.
@ -1976,11 +2005,10 @@ function hook_field_storage_delete_instance($instance) {
* that your module has already loaded a field.
* @param $options
* An associative array of additional options, with the following keys:
* - field_id: The field ID that should be loaded. If unset, all fields
* should be loaded.
* - deleted: If TRUE, deleted fields should be loaded as well as
* non-deleted fields. If unset or FALSE, only non-deleted fields should be
* loaded.
* - field_id: The field ID that should be loaded. If unset, all fields should
* be loaded.
* - deleted: If TRUE, deleted fields should be loaded as well as non-deleted
* fields. If unset or FALSE, only non-deleted fields should be loaded.
*/
function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) {
// @todo Needs function body.
@ -2103,7 +2131,7 @@ function hook_field_info_max_weight($entity_type, $bundle, $context) {
}
/**
* Alters the display settings of a field before it gets displayed.
* Alters the display settings of a field before it is displayed.
*
* Note that instead of hook_field_display_alter(), which is called for all
* fields on all entity types, hook_field_display_ENTITY_TYPE_alter() may be
@ -2138,7 +2166,7 @@ function hook_field_display_alter(&$display, $context) {
}
/**
* Alters the display settings of a field on a given entity type before it gets displayed.
* Alters the display settings of a field before it is displayed.
*
* Modules can implement hook_field_display_ENTITY_TYPE_alter() to alter display
* settings for fields on a specific entity type, rather than implementing
@ -2176,8 +2204,8 @@ function hook_field_display_ENTITY_TYPE_alter(&$display, $context) {
* cache the information.
*
* @param $displays
* An array of display settings for the pseudo-fields in the entity, keyed
* by pseudo-field names.
* An array of display settings for the pseudo-fields in the entity, keyed by
* pseudo-field names.
* @param $context
* An associative array containing:
* - entity_type: The entity type; e.g., 'node' or 'user'.
@ -2381,11 +2409,11 @@ function hook_field_read_instance($instance) {
/**
* Acts when a field record is being purged.
*
* In field_purge_field(), after the field configuration has been
* removed from the database, the field storage module has had a chance to
* run its hook_field_storage_purge_field(), and the field info cache
* has been cleared, this hook is invoked on all modules to allow them to
* respond to the field being purged.
* In field_purge_field(), after the field configuration has been removed from
* the database, the field storage module has had a chance to run its
* hook_field_storage_purge_field(), and the field info cache has been cleared,
* this hook is invoked on all modules to allow them to respond to the field
* being purged.
*
* @param $field
* The field being purged.
@ -2399,11 +2427,11 @@ function hook_field_purge_field($field) {
/**
* Acts when a field instance is being purged.
*
* In field_purge_instance(), after the field instance has been
* removed from the database, the field storage module has had a chance to
* run its hook_field_storage_purge_instance(), and the field info cache
* has been cleared, this hook is invoked on all modules to allow them to
* respond to the field instance being purged.
* In field_purge_instance(), after the field instance has been removed from the
* database, the field storage module has had a chance to run its
* hook_field_storage_purge_instance(), and the field info cache has been
* cleared, this hook is invoked on all modules to allow them to respond to the
* field instance being purged.
*
* @param $instance
* The instance being purged.
@ -2417,8 +2445,8 @@ function hook_field_purge_instance($instance) {
/**
* Remove field storage information when a field record is purged.
*
* Called from field_purge_field() to allow the field storage module
* to remove field information when a field is being purged.
* Called from field_purge_field() to allow the field storage module to remove
* field information when a field is being purged.
*
* @param $field
* The field being purged.
@ -2433,9 +2461,8 @@ function hook_field_storage_purge_field($field) {
/**
* Remove field storage information when a field instance is purged.
*
* Called from field_purge_instance() to allow the field storage module
* to remove field instance information when a field instance is being
* purged.
* Called from field_purge_instance() to allow the field storage module to
* remove field instance information when a field instance is being purged.
*
* @param $instance
* The instance being purged.
@ -2449,8 +2476,8 @@ function hook_field_storage_purge_field_instance($instance) {
/**
* Remove field storage information when field data is purged.
*
* Called from field_purge_data() to allow the field storage
* module to delete field data information.
* Called from field_purge_data() to allow the field storage module to delete
* field data information.
*
* @param $entity_type
* The type of $entity; for example, 'node' or 'user'.

271
core/modules/field/field.attach.inc
View File

@ -11,7 +11,7 @@ use Drupal\Core\Entity\EntityInterface;
/**
* @defgroup field_storage Field Storage API
* @{
* Implement a storage engine for Field API data.
* Implements a storage engine for Field API data.
*
* The Field Attach API uses the Field Storage API to perform all "database
* access". Each Field Storage API hook function defines a primitive database
@ -31,8 +31,7 @@ use Drupal\Core\Entity\EntityInterface;
/**
* Argument for an update operation.
*
* This is used in hook_field_storage_write when updating an
* existing entity.
* This is used in hook_field_storage_write when updating an existing entity.
*/
const FIELD_STORAGE_UPDATE = 'update';
@ -50,7 +49,7 @@ const FIELD_STORAGE_INSERT = 'insert';
/**
* @defgroup field_attach Field Attach API
* @{
* Operate on Field API data attached to Drupal entities.
* Operates on Field API data attached to Drupal entities.
*
* Field Attach API functions load, store, display, generate Field API
* structures, and perform a variety of other functions for field data attached
@ -61,18 +60,18 @@ const FIELD_STORAGE_INSERT = 'insert';
* 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.
* 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:
* 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
@ -89,16 +88,16 @@ const FIELD_STORAGE_INSERT = 'insert';
*
* 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.
* 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.
* Field Storage API is essentially the "fallback mechanism" for any fields that
* aren't being intercepted explicitly by pre-operation hooks.
*
* @link field_language Field language API @endlink provides information about
* the structure of field objects.
@ -298,7 +297,7 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
}
/**
* Invoke a field hook across fields on multiple entities.
* Invokes a field hook across fields on multiple entities.
*
* @param $op
* Possible operations include:
@ -307,9 +306,9 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
* For all other operations, use _field_invoke() / field_invoke_default()
* instead.
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* The type of entities in $entities; e.g. 'node' or 'user'.
* @param $entities
* An array of entities, keyed by entity id.
* An array of entities, keyed by entity ID.
* @param $a
* - The $age parameter in the 'load' operation.
* - Otherwise NULL.
@ -317,30 +316,30 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
* Currently always NULL.
* @param $options
* An associative array of additional options, with the following keys:
* - 'field_name': The name of the field whose operation should be
* invoked. By default, the operation is invoked on all the fields
* in the entity's bundle. NOTE: This option is not compatible with
* the 'deleted' option; the 'field_id' option should be used instead.
* - 'field_id': The id of the field whose operation should be
* invoked. By default, the operation is invoked on all the fields
* in the entity's' bundles.
* - 'default': A boolean value, specifying which implementation of
* the operation should be invoked.
* - if FALSE (default), the field types implementation of the operation
* will be invoked (hook_field_[op])
* - If TRUE, the default field implementation of the field operation
* will be invoked (field_default_[op])
* Internal use only. Do not explicitely set to TRUE, but use
* _field_invoke_multiple_default() instead.
* - 'deleted': If TRUE, the function will operate on deleted fields
* as well as non-deleted fields. If unset or FALSE, only
* non-deleted fields are operated on.
* - 'langcode': A language code or an array of arrays of language codes keyed
* by entity id and field name. It will be used to narrow down to a single
* value the available language codes to act on.
* - field_name: The name of the field whose operation should be invoked. By
* default, the operation is invoked on all the fields in the entity's
* bundle. NOTE: This option is not compatible with the 'deleted' option;
* the 'field_id' option should be used instead.
* - field_id: The ID of the field whose operation should be invoked. By
* default, the operation is invoked on all the fields in the entity's
* bundles.
* - default: A boolean value, specifying which implementation of the
* operation should be invoked.
* - if FALSE (default), the field types implementation of the operation
* will be invoked (hook_field_[op])
* - If TRUE, the default field implementation of the field operation will
* be invoked (field_default_[op])
* Internal use only. Do not explicitely set to TRUE, but use
* _field_invoke_multiple_default() instead.
* - deleted: If TRUE, the function will operate on deleted fields as well as
* non-deleted fields. If unset or FALSE, only non-deleted fields are
* operated on.
* - langcode: A language code or an array of arrays of language codes keyed
* by entity ID and field name. It will be used to narrow down to a single
* value the available languages to act on.
*
* @return
* An array of returned values keyed by entity id.
* An array of returned values keyed by entity ID.
*/
function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {
// Merge default options.
@ -361,7 +360,7 @@ function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b =
// Go through the entities and collect the fields on which the hook should be
// invoked.
//
// We group fields by id, not by name, because this function can operate on
// We group fields by ID, not by name, because this function can operate on
// deleted fields which may have non-unique names. However, entities can only
// contain data for a single field for each name, even if that field
// is deleted, so we reference field data via the
@ -460,6 +459,48 @@ function _field_invoke_default($op, $entity_type, EntityInterface $entity, &$a =
* Use _field_invoke_multiple() to invoke the field type implementation,
* hook_field_[op]().
*
* @param $op
* Possible operations include:
* - load
* - prepare_view
* For all other operations, use _field_invoke() / field_invoke_default()
* instead.
* @param $entity_type
* The type of entities in $entities; e.g. 'node' or 'user'.
* @param $entities
* An array of entities, keyed by entity ID.
* @param $a
* - The $age parameter in the 'load' operation.
* - Otherwise NULL.
* @param $b
* Currently always NULL.
* @param $options
* An associative array of additional options, with the following keys:
* - field_name: The name of the field whose operation should be invoked. By
* default, the operation is invoked on all the fields in the entity's
* bundle. NOTE: This option is not compatible with the 'deleted' option;
* the 'field_id' option should be used instead.
* - field_id: The ID of the field whose operation should be invoked. By
* default, the operation is invoked on all the fields in the entity's
* bundles.
* - default': A boolean value, specifying which implementation of the
* operation should be invoked.
* - if FALSE (default), the field types implementation of the operation
* will be invoked (hook_field_[op])
* - If TRUE, the default field implementation of the field operation will
* be invoked (field_default_[op])
* Internal use only. Do not explicitely set to TRUE, but use
* _field_invoke_multiple_default() instead.
* - deleted: If TRUE, the function will operate on deleted fields as well as
* non-deleted fields. If unset or FALSE, only non-deleted fields are
* operated on.
* - language: A language code or an array of arrays of language codes keyed
* by entity ID and field name. It will be used to narrow down to a single
* value the available languages to act on.
*
* @return
* An array of returned values keyed by entity ID.
*
* @see _field_invoke_multiple()
*/
function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {
@ -468,7 +509,9 @@ function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL
}
/**
* Helper for _field_invoke(): retrieves a list of instances to operate on.
* Retrieves a list of instances to operate on.
*
* Helper for _field_invoke().
*
* @param $entity_type
* The entity type.
@ -476,7 +519,7 @@ function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL
* The bundle name.
* @param $options
* An associative array of options, as provided to _field_invoke(). Only the
* following keys are considered :
* following keys are considered:
* - deleted
* - field_name
* - field_id
@ -535,7 +578,7 @@ function _field_invoke_widget_target() {
}
/**
* Add form elements for all fields for an entity to a form structure.
* Adds form elements for all fields for an entity to a form structure.
*
* The form elements for the entity's fields are added by reference as direct
* children in the $form parameter. This parameter can be a full form structure
@ -672,26 +715,25 @@ function field_attach_form($entity_type, EntityInterface $entity, &$form, &$form
* entity type module.
*
* @param $entity_type
* The type of $entity; e.g., 'node' or 'user'.
* The type of entities in $entities; e.g., 'node' or 'user'.
* @param $entities
* An array of entities for which to load fields, keyed by entity ID.
* Each entity needs to have its 'bundle', 'id' and (if applicable)
* 'revision' keys filled in. The function adds the loaded field data
* directly in the entity objects of the $entities array.
* An array of entities for which to load fields, keyed by entity ID. Each
* entity needs to have its 'bundle', 'id' and (if applicable) 'revision' keys
* filled in. The function adds the loaded field data directly in the entity
* objects of the $entities array.
* @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 entity. Defaults to FIELD_LOAD_CURRENT; use
* field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.
* FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
* FIELD_LOAD_REVISION to load the version indicated by each entity. Defaults
* to FIELD_LOAD_CURRENT; use field_attach_load_revision() instead of passing
* FIELD_LOAD_REVISION.
* @param $options
* An associative array of additional options, with the following keys:
* - 'field_id': The field ID that should be loaded, instead of
* loading all fields, for each entity. Note that returned entities
* may contain data for other fields, for example if they are read
* from a cache.
* - 'deleted': If TRUE, the function will operate on deleted fields
* as well as non-deleted fields. If unset or FALSE, only
* non-deleted fields are operated on.
* - field_id: The field ID that should be loaded, instead of loading all
* fields, for each entity. Note that returned entities may contain data for
* other fields, for example if they are read from a cache.
* - deleted: If TRUE, the function will operate on deleted fields as well as
* non-deleted fields. If unset or FALSE, only non-deleted fields are
* operated on.
*/
function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $options = array()) {
$field_info = field_info_field_by_ids();
@ -808,7 +850,7 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $
}
/**
* Load all fields for previous versions of a group of entities.
* Loads all fields for previous versions of a group of entities.
*
* Loading different versions of the same entities is not supported, and should
* be done by separate calls to the function.
@ -818,12 +860,12 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $
* called by the entity type module.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
* The type of entities in $entities; e.g. 'node' or 'user'.
* @param $entities
* An array of entities for which to load fields, keyed by entity ID. Each
* entity needs to have its 'bundle', 'id' and (if applicable) 'revision'
* keys filled. The function adds the loaded field data directly in the
* entity objects of the $entities array.
* entity needs to have its 'bundle', 'id' and (if applicable) 'revision' keys
* filled. The function adds the loaded field data directly in the entity
* objects of the $entities array.
* @param $options
* An associative array of additional options. See field_attach_load() for
* details.
@ -833,12 +875,11 @@ function field_attach_load_revision($entity_type, $entities, $options = array())
}
/**
* Perform field validation against the field data in an entity.
* Performs field validation against the field data in an entity.
*
* This function does not perform field widget validation on form
* submissions. It is intended to be called during API save
* operations. Use field_attach_form_validate() to validate form
* submissions.
* This function does not perform field widget validation on form submissions.
* It is intended to be called during API save operations. Use
* field_attach_form_validate() to validate form submissions.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -869,21 +910,21 @@ function field_attach_validate($entity_type, $entity) {
}
/**
* Perform field validation against form-submitted field values.
* Performs field validation against form-submitted field values.
*
* There are two levels of validation for fields in forms: widget
* validation, and field validation.
* - Widget validation steps are specific to a given widget's own form
* structure and UI metaphors. They are executed through FAPI's
* #element_validate property during normal form validation.
* There are two levels of validation for fields in forms: widget validation and
* and field validation.
* - Widget validation steps are specific to a given widget's own form structure
* and UI metaphors. They are executed through FAPI's #element_validate
* property during normal form validation.
* - Field validation steps are common to a given field type, independently of
* the specific widget being used in a given form. They are defined in the
* field type's implementation of hook_field_validate().
*
* This function performs field validation in the context of a form
* submission. It converts field validation errors into form errors
* on the correct form elements. Fieldable entity types should call
* this function during their own form validation function.
* This function performs field validation in the context of a form submission.
* It converts field validation errors into form errors on the correct form
* elements. Fieldable entity types should call this function during their own
* form validation function.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -917,10 +958,10 @@ function field_attach_form_validate($entity_type, EntityInterface $entity, $form
}
/**
* Perform necessary operations on field data submitted by a form.
* Performs necessary operations on field data submitted by a form.
*
* Currently, this accounts for drag-and-drop reordering of
* field values, and filtering of empty values.
* Currently, this accounts for drag-and-drop reordering of field values, and
* filtering of empty values.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -947,10 +988,10 @@ function field_attach_submit($entity_type, EntityInterface $entity, $form, &$for
}
/**
* Perform necessary operations just before fields data get saved.
* Performs necessary operations just before fields data get saved.
*
* We take no specific action here, we just give other
* modules the opportunity to act.
* We take no specific action here, we just give other modules the opportunity
* to act.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -1019,7 +1060,7 @@ function field_attach_insert($entity_type, EntityInterface $entity) {
}
/**
* Save field data for an existing entity.
* Saves field data for an existing entity.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -1071,8 +1112,8 @@ function field_attach_update($entity_type, EntityInterface $entity) {
}
/**
* Delete field data for an existing entity. This deletes all
* revisions of field data for the entity.
* Deletes field data for an existing entity. This deletes all revisions of
* field data for the entity.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -1106,8 +1147,8 @@ function field_attach_delete($entity_type, $entity) {
}
/**
* Delete field data for a single revision of an existing entity. The
* passed entity must have a revision id attribute.
* Delete field data for a single revision of an existing entity. The passed
* entity must have a revision ID attribute.
*
* @param $entity_type
* The type of $entity; e.g. 'node' or 'user'.
@ -1136,24 +1177,23 @@ function field_attach_delete_revision($entity_type, $entity) {
}
/**
* Prepare field data prior to display.
* Prepares field data prior to display.
*
* This function lets field types and formatters load additional data
* needed for display that is not automatically loaded during
* field_attach_load(). It accepts an array of entities to allow query
* optimisation when displaying lists of entities.
* This function lets field types and formatters load additional data needed for
* display that is not automatically loaded during field_attach_load(). It
* accepts an array of entities to allow query optimization when displaying
* lists of entities.
*
* field_attach_prepare_view() and field_attach_view() are two halves
* of the same operation. It is safe to call
* field_attach_prepare_view() multiple times on the same entity
* before calling field_attach_view() on it, but calling any Field
* API operation on an entity between passing that entity to these two
* field_attach_prepare_view() and field_attach_view() are two halves of the
* same operation. It is safe to call field_attach_prepare_view() multiple times
* on the same entity before calling field_attach_view() on it, but calling any
* Field API operation on an entity between passing that entity to these two
* functions may yield incorrect results.
*
* @param $entity_type
* The type of $entities; e.g. 'node' or 'user'.
* The type of entities in $entities; e.g. 'node' or 'user'.
* @param $entities
* An array of entities, keyed by entity id.
* An array of entities, keyed by entity ID.
* @param $view_mode
* View mode, e.g. 'full', 'teaser'...
* @param $langcode
@ -1194,13 +1234,12 @@ function field_attach_prepare_view($entity_type, $entities, $view_mode, $langcod
* Returns a renderable array for the fields on an entity.
*
* Each field is displayed according to the display options specified in the
* $instance definition for the given $view_mode.
* instance definition for the given view mode.
*
* field_attach_prepare_view() and field_attach_view() are two halves
* of the same operation. It is safe to call
* field_attach_prepare_view() multiple times on the same entity
* before calling field_attach_view() on it, but calling any Field
* API operation on an entity between passing that entity to these two
* field_attach_prepare_view() and field_attach_view() are two halves of the
* same operation. It is safe to call field_attach_prepare_view() multiple times
* on the same entity before calling field_attach_view() on it, but calling any
* Field API operation on an entity between passing that entity to these two
* functions may yield incorrect results.
*
* Sample structure:
@ -1270,7 +1309,7 @@ function field_attach_view($entity_type, EntityInterface $entity, $view_mode, $l
}
/**
* Populate the template variables with the field values available for rendering.
* Populates the template variables with the available field values.
*
* The $variables array will be populated with all the field instance values
* associated with the given entity type, keyed by field name; in case of
@ -1308,7 +1347,7 @@ function field_attach_preprocess($entity_type, EntityInterface $entity, $element
/**
* Prepares an entity for translation.
*
* This function is used to fill-in the form default values for Field API fields
* This function is used to fill in the form default values for Field API fields
* while performing entity translation. By default it copies all the source
* values in the given source language to the new entity and assigns them the
* target language.
@ -1345,7 +1384,7 @@ function field_attach_prepare_translation($entity_type, EntityInterface $entity,
}
/**
* Notify field.module that a new bundle was created.
* Notifies field.module that a new bundle was created.
*
* The default SQL-based storage doesn't need to do anything about it, but
* others might.
@ -1364,7 +1403,7 @@ function field_attach_create_bundle($entity_type, $bundle) {
}
/**
* Notify field.module that a bundle was renamed.
* Notifies field.module that a bundle was renamed.
*
* @param $entity_type
* The entity type to which the bundle is bound.
@ -1394,12 +1433,12 @@ function field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
}
/**
* Notify field.module the a bundle was deleted.
* Notifies field.module the a bundle was deleted.
*
* This deletes the data for the field instances as well as the field instances
* themselves. This function actually just marks the data and field instances
* and deleted, leaving the garbage collection for a separate process, because
* it is not always possible to delete this much data in a single page request
* themselves. This function actually just marks the data and field instances as
* deleted, leaving the garbage collection for a separate process, because it is
* not always possible to delete this much data in a single page request
* (particularly since for some field types, the deletion is more than just a
* simple DELETE query).
*

116
core/modules/field/field.crud.inc
View File

@ -11,13 +11,12 @@ use Drupal\Core\Entity\EntityFieldQuery;
/**
* @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

49
core/modules/field/field.default.inc
View File

@ -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'];

47
core/modules/field/field.form.inc
View File

@ -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.
* 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.
*
* @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.

87
core/modules/field/field.info.inc
View File

@ -10,11 +10,11 @@ use Drupal\field\FieldInstance;
/**
* @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 @@ use Drupal\field\FieldInstance;
/**
* 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.

16
core/modules/field/field.install
View File

@ -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
*/

373
core/modules/field/field.module
View File

@ -22,166 +22,162 @@ require_once DRUPAL_ROOT . '/core/modules/field/field.form.inc';
/**
* @defgroup field Field API
* @{
* Attach custom data fields to Drupal entities.
* Attaches custom data fields to Drupal entities.
*
* The Field API allows custom data fields to be attached to Drupal
* entities and takes care of storing, loading, editing, and rendering
* field data. Any entity type (node, user, etc.) can use the Field
* API to make itself "fieldable" and thus allow fields to be attached
* to it. Other modules can provide a user interface for managing custom
* fields via a web browser as well as a wide and flexible variety of
* data type, form element, and display format capabilities.
* The Field API allows custom data fields to be attached to Drupal entities and
* takes care of storing, loading, editing, and rendering field data. Any entity
* type (node, user, etc.) can use the Field API to make itself "fieldable" and
* thus allow fields to be attached to it. Other modules can provide a user
* interface for managing custom fields via a web browser as well as a wide and
* flexible variety of data type, form element, and display format capabilities.
*
* The Field API defines two primary data structures, Field and
* Instance, and the concept of a Bundle. A Field defines a
* particular type of data that can be attached to entities. A Field
* Instance is a Field attached to a single Bundle. A Bundle is a set
* of fields that are treated as a group by the Field Attach API and
* is related to a single fieldable entity type.
* The Field API defines two primary data structures, Field and Instance, and
* the concept of a Bundle. A Field defines a particular type of data that can
* be attached to entities. A Field Instance is a Field attached to a single
* Bundle. A Bundle is a set of fields that are treated as a group by the Field
* Attach API and is related to a single fieldable entity type.
*
* For example, suppose a site administrator wants Article nodes to
* have a subtitle and photo. Using the Field API or Field UI module,
* the administrator creates a field named 'subtitle' of type 'text'
* and a field named 'photo' of type 'image'. The administrator
* (again, via a UI) creates two Field Instances, one attaching the
* field 'subtitle' to the 'node' bundle 'article' and one attaching
* the field 'photo' to the 'node' bundle 'article'. When the node
* system uses the Field Attach API to load all fields for an Article
* node, it passes the node's entity type (which is 'node') and
* content type (which is 'article') as the node's bundle.
* field_attach_load() then loads the 'subtitle' and 'photo' fields
* because they are both attached to the 'node' bundle 'article'.
* For example, suppose a site administrator wants Article nodes to have a
* subtitle and photo. Using the Field API or Field UI module, the administrator
* creates a field named 'subtitle' of type 'text' and a field named 'photo' of
* type 'image'. The administrator (again, via a UI) creates two Field
* Instances, one attaching the field 'subtitle' to the 'node' bundle 'article'
* and one attaching the field 'photo' to the 'node' bundle 'article'. When the
* node system uses the Field Attach API to load all fields for an Article node,
* it passes the node's entity type (which is 'node') and content type (which is
* 'article') as the node's bundle. field_attach_load() then loads the
* 'subtitle' and 'photo' fields because they are both attached to the 'node'
* bundle 'article'.
*
* Field definitions are represented as an array of key/value pairs.
*
* array $field:
* - id (integer, read-only): The primary identifier of the field. It is
* - id: (integer, read-only) The primary identifier of the field. It is
* assigned automatically by field_create_field().
* - field_name (string): The name of the field. Each field name is unique
* - field_name: (string) The name of the field. Each field name is unique
* within Field API. When a field is attached to an entity, the field's data
* is stored in $entity->$field_name. Maximum length is 32 characters.
* - type (string): The type of the field, such as 'text' or 'image'. Field
* - type: (string) The type of the field, such as 'text' or 'image'. Field
* types are defined by modules that implement hook_field_info().
* - entity_types (array): The array of entity types that can hold instances
* of this field. If empty or not specified, the field can have instances
* in any entity type.
* - cardinality (integer): The number of values the field can hold. Legal
* - entity_types: (array) The array of entity types that can hold instances of
* this field. If empty or not specified, the field can have instances in any
* entity type.
* - cardinality: (integer) The number of values the field can hold. Legal
* values are any positive integer or FIELD_CARDINALITY_UNLIMITED.
* - translatable (integer): Whether the field is translatable.
* - locked (integer): Whether or not the field is available for editing. If
* - translatable: (integer) Whether the field is translatable.
* - locked: (integer) Whether or not the field is available for editing. If
* TRUE, users can't change field settings or create new instances of the
* field in the UI. Defaults to FALSE.
* - module (string, read-only): The name of the module that implements the
* - module: (string, read-only) The name of the module that implements the
* field type.
* - active (integer, read-only): TRUE if the module that implements the field
* - active: (integer, read-only) TRUE if the module that implements the field
* type is currently enabled, FALSE otherwise.
* - deleted (integer, read-only): TRUE if this field has been deleted, FALSE
* - deleted: (integer, read-only) TRUE if this field has been deleted, FALSE
* otherwise. Deleted fields are ignored by the Field Attach API. This
* property exists because fields can be marked for deletion but only
* actually destroyed by a separate garbage-collection process.
* - columns (array, read-only): An array of the Field API columns used to
* store each value of this field. The column list may depend on field
* settings; it is not constant per field type. Field API column
* specifications are exactly like Schema API column specifications but,
* depending on the field storage module in use, the name of the column may
* not represent an actual column in an SQL database.
* - indexes (array): An array of indexes on data columns, using the same
* property exists because fields can be marked for deletion but only actually
* destroyed by a separate garbage-collection process.
* - columns: (array, read-only) An array of the Field API columns used to store
* each value of this field. The column list may depend on field settings; it
* is not constant per field type. Field API column specifications are exactly
* like Schema API column specifications but, depending onthe field storage
* module in use, the name of the column may not represent an actual column in
* an SQL database.
* - indexes: (array) An array of indexes on data columns, using the same
* definition format as Schema API index specifications. Only columns that
* appear in the 'columns' setting are allowed. Note that field types can
* specify default indexes, which can be modified or added to when
* creating a field.
* specify default indexes, which can be modified or added to when creating a
* field.
* - foreign keys: (optional) An associative array of relations, using the same
* structure as the 'foreign keys' definition of hook_schema(). Note,
* however, that the field data is not necessarily stored in SQL. Also, the
* possible usage is limited, as you cannot specify another field as
* related, only existing SQL tables, such as filter formats.
* - settings (array): A sub-array of key/value pairs of field-type-specific
* - settings: (array) A sub-array of key/value pairs of field-type-specific
* settings. Each field type module defines and documents its own field
* settings.
* - storage (array): A sub-array of key/value pairs identifying the storage
* backend to use for the for the field:
* - type (string): The storage backend used by the field. Storage backends
* - storage: (array) A sub-array of key/value pairs identifying the storage
* backend to use for the for the field.
* - type: (string) The storage backend used by the field. Storage backends
* are defined by modules that implement hook_field_storage_info().
* - module (string, read-only): The name of the module that implements the
* - module: (string, read-only) The name of the module that implements the
* storage backend.
* - active (integer, read-only): TRUE if the module that implements the
* - active: (integer, read-only) TRUE if the module that implements the
* storage backend is currently enabled, FALSE otherwise.
* - settings (array): A sub-array of key/value pairs of settings. Each
* - settings: (array) A sub-array of key/value pairs of settings. Each
* storage backend defines and documents its own settings.
*
* Field instance definitions are represented as an array of key/value pairs.
*
* array $instance:
* - id (integer, read-only): The primary identifier of this field instance.
* It is assigned automatically by field_create_instance().
* - field_id (integer, read-only): The foreign key of the field attached to
* the bundle by this instance. It is populated automatically by
* - id: (integer, read-only) The primary identifier of this field instance. It
* is assigned automatically by field_create_instance().
* - field_id: (integer, read-only) The foreign key of the field attached to the
* bundle by this instance. It is populated automatically by
* field_create_instance().
* - field_name (string): The name of the field attached to the bundle by this
* - field_name: (string) The name of the field attached to the bundle by this
* instance.
* - entity_type (string): The name of the entity type the instance is attached
* - entity_type: (string) The name of the entity type the instance is attached
* to.
* - bundle (string): The name of the bundle that the field is attached to.
* - label (string): A human-readable label for the field when used with this
* bundle. For example, the label will be the title of Form API elements
* for this instance.
* - description (string): A human-readable description for the field when
* used with this bundle. For example, the description will be the help
* text of Form API elements for this instance.
* - required (integer): TRUE if a value for this field is required when used
* - bundle: (string) The name of the bundle that the field is attached to.
* - label: (string) A human-readable label for the field when used with this
* bundle. For example, the label will be the title of Form API elements for
* this instance.
* - description: (string)A human-readable description for the field when used
* with this bundle. For example, the description will be the help text of
* Form API elements for this instance.
* - required: (integer) TRUE if a value for this field is required when used
* with this bundle, FALSE otherwise. Currently, required-ness is only
* enforced during Form API operations, not by field_attach_load(),
* field_attach_insert(), or field_attach_update().
* - default_value_function (string): The name of the function, if any, that
* - default_value_function: (string) The name of the function, if any, that
* will provide a default value.
* - default_value (array): If default_value_function is not set, then fixed
* - default_value: (array) If default_value_function is not set, then fixed
* values can be provided.
* - deleted (integer, read-only): TRUE if this instance has been deleted,
* FALSE otherwise. Deleted instances are ignored by the Field Attach API.
* This property exists because instances can be marked for deletion but
* only actually destroyed by a separate garbage-collection process.
* - settings (array): A sub-array of key/value pairs of field-type-specific
* - deleted: (integer, read-only) TRUE if this instance has been deleted, FALSE
* otherwise. Deleted instances are ignored by the Field Attach API. This
* property exists because instances can be marked for deletion but only
* actually destroyed by a separate garbage-collection process.
* - settings: (array) A sub-array of key/value pairs of field-type-specific
* instance settings. Each field type module defines and documents its own
* instance settings.
* - widget (array): A sub-array of key/value pairs identifying the Form API
* input widget for the field when used by this bundle:
* - type (string): The type of the widget, such as text_textfield. Widget
* - widget: (array) A sub-array of key/value pairs identifying the Form API
* input widget for the field when used by this bundle.
* - type: (string) The type of the widget, such as text_textfield. Widget
* types are defined by modules that implement hook_field_widget_info().
* - settings (array): A sub-array of key/value pairs of
* widget-type-specific settings. Each field widget type module defines
* and documents its own widget settings.
* - weight (float): The weight of the widget relative to the other elements
* - settings: (array) A sub-array of key/value pairs of widget-type-specific
* settings. Each field widget type module defines and documents its own
* widget settings.
* - weight: (float) The weight of the widget relative to the other elements
* in entity edit forms.
* - module (string, read-only): The name of the module that implements the
* - module: (string, read-only) The name of the module that implements the
* widget type.
* - display (array): A sub-array of key/value pairs identifying the way field
* - display: (array) A sub-array of key/value pairs identifying the way field
* values should be displayed in each of the entity type's view modes, plus
* the 'default' mode. For each view mode, Field UI lets site administrators
* define whether they want to use a dedicated set of display options or the
* 'default' options to reduce the number of displays to maintain as they
* add new fields. For nodes, on a fresh install, only the 'teaser' view
* mode is configured to use custom display options, all other view modes
* defined use the 'default' options by default. When programmatically
* adding field instances on nodes, it is therefore recommended to at least
* specify display options for 'default' and 'teaser':
* - default (array): A sub-array of key/value pairs describing the display
* options to be used when the field is being displayed in view modes
* that are not configured to use dedicated display options:
* - label (string): Position of the label. 'inline', 'above' and
* 'hidden' are the values recognized by the default 'field' theme
* implementation.
* - type (string): The type of the display formatter, or 'hidden' for
* no display.
* - settings (array): A sub-array of key/value pairs of display
* options specific to the formatter.
* - weight (float): The weight of the field relative to the other entity
* components displayed in this view mode.
* - module (string, read-only): The name of the module which implements
* the display formatter.
* - some_mode: A sub-array of key/value pairs describing the display
* options to be used when the field is being displayed in the 'some_mode'
* view mode. Those options will only be actually applied at run time if
* the view mode is not configured to use default settings for this bundle:
* 'default' options to reduce the number of displays to maintain as they add
* new fields. For nodes, on a fresh install, only the 'teaser' view mode is
* configured to use custom display options, all other view modes defined use
* the 'default' options by default. When programmatically adding field
* instances on nodes, it is therefore recommended to at least specify display
* options for 'default' and 'teaser'.
* - default: (array) A sub-array of key/value pairs describing the display
* options to be used when the field is being displayed in view modes that
* are not configured to use dedicated display options.
* - label: (string) Position of the label. 'inline', 'above' and 'hidden'
* are the values recognized by the default 'field' theme implementation.
* - type: (string) The type of the display formatter, or 'hidden' for no
* display.
* - settings: (array) A sub-array of key/value pairs of display options
* specific to the formatter.
* - weight: (float) The weight of the field relative to the other entity
* components displayed in this view mode.
* - module: (string, read-only) The name of the module which implements
* the display formatter.
* - some_mode: A sub-array of key/value pairs describing the display options
* to be used when the field is being displayed in the 'some_mode' view
* mode. Those options will only be actually applied at run time if the view
* mode is not configured to use default settings for this bundle.
* - ...
* - other_mode:
* - ...
@ -191,37 +187,34 @@ require_once DRUPAL_ROOT . '/core/modules/field/field.form.inc';
*
* Bundles are represented by two strings, an entity type and a bundle name.
*
* - @link field_types Field Types API @endlink. Defines field types,
* widget types, and display formatters. Field modules use this API
* to provide field types like Text and Node Reference along with the
* associated form elements and display formatters.
* - @link field_types Field Types API @endlink: Defines field types, widget
* types, and display formatters. Field modules use this API to provide field
* types like Text and Node Reference along with the associated form elements
* and display formatters.
*
* - @link field_crud Field CRUD API @endlink. Create, updates, and
* deletes fields, bundles (a.k.a. "content types"), and instances.
* Modules use this API, often in hook_install(), to create
* custom data structures.
* - @link field_crud Field CRUD API @endlink: Create, updates, and deletes
* fields, bundles (a.k.a. "content types"), and instances. Modules use this
* API, often in hook_install(), to create custom data structures.
*
* - @link field_attach Field Attach API @endlink. Connects entity
* types to the Field API. 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.
* Fieldable entity types like node and user use this API to make
* themselves fieldable.
* - @link field_attach Field Attach API @endlink: Connects entity types to the
* Field API. 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. Fieldable entity types like node and
* user use this API to make themselves fieldable.
*
* - @link field_info Field Info API @endlink. Exposes information
* about all fields, instances, widgets, and related information
* defined by or with the Field API.
* - @link field_info Field Info API @endlink: Exposes information about all
* fields, instances, widgets, and related information defined by or with the
* Field API.
*
* - @link field_storage Field Storage API @endlink. Provides a
* pluggable back-end storage system for actual field data. The
* default implementation, field_sql_storage.module, stores field data
* in the local SQL database.
* - @link field_storage Field Storage API @endlink: Provides a pluggable back
* -end storage system for actual field data. The default implementation,
* field_sql_storage.module, stores field data in the local SQL database.
*
* - @link field_purge Field API bulk data deletion @endlink. Cleans
* up after bulk deletion operations such as field_delete_field()
* and field_delete_instance().
* - @link field_purge Field API bulk data deletion @endlink: Cleans up after
* bulk deletion operations such as field_delete_field() and
* field_delete_instance().
*
* - @link field_language Field language API @endlink. Provides native
* - @link field_language Field language API @endlink: Provides native
* multilingual support for the Field API.
*/
@ -257,14 +250,16 @@ const FIELD_BEHAVIOR_DEFAULT = 0x0002;
const FIELD_BEHAVIOR_CUSTOM = 0x0004;
/**
* Age argument for loading the most recent version of an entity's
* field data with field_attach_load().
* Load the most recent version of an entity's field data.
*
* @see field_attach_load().
*/
const FIELD_LOAD_CURRENT = 'FIELD_LOAD_CURRENT';
/**
* Age argument for loading the version of an entity's field data
* specified in the entity with field_attach_load().
* Load the version of an entity's field data specified in the entity.
*
* @see field_attach_load().
*/
const FIELD_LOAD_REVISION = 'FIELD_LOAD_REVISION';
@ -335,7 +330,7 @@ function field_cron() {
/**
* Implements hook_system_info_alter().
*
* Goes through a list of all modules that provide a field type, and makes them
* Goes through a list of all modules that provide a field type and makes them
* required if there are any active fields of that type.
*/
function field_system_info_alter(&$info, $file, $type) {
@ -545,7 +540,7 @@ function field_get_default_value($entity_type, $entity, $field, $instance, $lang
}
/**
* Helper function to filter out empty field values.
* Filters out empty field values.
*
* @param $field
* The field definition.
@ -568,8 +563,15 @@ function _field_filter_items($field, $items) {
}
/**
* Helper function to sort items in a field according to
* user drag-n-drop reordering.
* Sorts items in a field according to user drag-and-drop reordering.
*
* @param $field
* The field definition.
* @param $items
* The field values to sort.
*
* @return
* The sorted array of field items.
*/
function _field_sort_items($field, $items) {
if (($field['cardinality'] > 1 || $field['cardinality'] == FIELD_CARDINALITY_UNLIMITED) && isset($items[0]['_weight'])) {
@ -584,8 +586,9 @@ function _field_sort_items($field, $items) {
}
/**
* Sort function for items order.
* (copied form element_sort(), which acts on #weight keys)
* Callback for usort() within _field_sort_items().
*
* Copied form element_sort(), which acts on #weight keys.
*/
function _field_sort_items_helper($a, $b) {
$a_weight = (is_array($a) ? $a['_weight'] : 0);
@ -594,7 +597,9 @@ function _field_sort_items_helper($a, $b) {
}
/**
* Same as above, using ['_weight']['#value']
* Callback for usort() within theme_field_multiple_value_form().
*
* Sorts using ['_weight']['#value']
*/
function _field_sort_items_value_helper($a, $b) {
$a_weight = (is_array($a) && isset($a['_weight']['#value']) ? $a['_weight']['#value'] : 0);
@ -759,7 +764,7 @@ function field_extra_fields_get_display($entity_type, $bundle, $view_mode) {
}
/**
* Pre-render callback to adjust weights and visibility of non-field elements.
* Pre-render callback: Adjusts weights and visibility of non-field elements.
*/
function _field_extra_fields_pre_render($elements) {
$entity_type = $elements['#entity_type'];
@ -789,7 +794,7 @@ function _field_extra_fields_pre_render($elements) {
}
/**
* Clear the field info and field data caches.
* Clears the field info and field data caches.
*/
function field_cache_clear() {
cache('field')->flush();
@ -797,25 +802,34 @@ function field_cache_clear() {
}
/**
* Filters an HTML string to prevent cross-site-scripting (XSS) vulnerabilities.
*
* Like filter_xss_admin(), but with a shorter list of allowed tags.
*
* Used for items entered by administrators, like field descriptions,
* allowed values, where some (mainly inline) mark-up may be desired
* (so check_plain() is not acceptable).
* Used for items entered by administrators, like field descriptions, allowed
* values, where some (mainly inline) mark-up may be desired (so
* drupal_htmlspecialchars() is not acceptable).
*
* @param $string
* The string with raw HTML in it.
*
* @return
* An XSS safe version of $string, or an empty string if $string is not valid
* UTF-8.
*/
function field_filter_xss($string) {
return filter_xss($string, _field_filter_xss_allowed_tags());
}
/**
* List of tags allowed by field_filter_xss().
* Returns a list of tags allowed by field_filter_xss().
*/
function _field_filter_xss_allowed_tags() {
return array('a', 'b', 'big', 'code', 'del', 'em', 'i', 'ins', 'pre', 'q', 'small', 'span', 'strong', 'sub', 'sup', 'tt', 'ol', 'ul', 'li', 'p', 'br', 'img');
}
/**
* Human-readable list of allowed tags, for display in help texts.
* Returns a human-readable list of allowed tags for display in help texts.
*/
function _field_filter_xss_display_allowed_tags() {
return '<' . implode('> <', _field_filter_xss_allowed_tags()) . '>';
@ -827,7 +841,7 @@ function _field_filter_xss_display_allowed_tags() {
* @param $entity_type
* The type of $entity; e.g., 'node' or 'user'.
* @param $entity
* The entity containing the field to display. Must at least contain the id
* The entity containing the field to display. Must at least contain the ID
* key and the field data to display.
* @param $field_name
* The name of the field to display.
@ -835,11 +849,12 @@ function _field_filter_xss_display_allowed_tags() {
* The field value to display, as found in
* $entity->field_name[$langcode][$delta].
* @param $display
* Can be either the name of a view mode, or an array of display settings.
* See field_view_field() for more information.
* Can be either the name of a view mode, or an array of display settings. See
* field_view_field() for more information.
* @param $langcode
* (Optional) The language of the value in $item. If not provided, the
* current language will be assumed.
* (Optional) The language of the value in $item. If not provided, the current
* language will be assumed.
*
* @return
* A renderable array for the field value.
*/
@ -886,7 +901,7 @@ function field_view_value($entity_type, $entity, $field_name, $item, $display =
* @param $entity_type
* The type of $entity; e.g., 'node' or 'user'.
* @param $entity
* The entity containing the field to display. Must at least contain the id
* The entity containing the field to display. Must at least contain the ID
* key and the field data to display.
* @param $field_name
* The name of the field to display.
@ -894,28 +909,28 @@ function field_view_value($entity_type, $entity, $field_name, $item, $display =
* Can be either:
* - The name of a view mode. The field will be displayed according to the
* display settings specified for this view mode in the $instance
* definition for the field in the entity's bundle.
* If no display settings are found for the view mode, the settings for
* the 'default' view mode will be used.
* definition for the field in the entity's bundle. If no display settings
* are found for the view mode, the settings for the 'default' view mode
* will be used.
* - An array of display settings, as found in the 'display' entry of
* $instance definitions. The following key/value pairs are allowed:
* - label: (string) Position of the label. The default 'field' theme
* implementation supports the values 'inline', 'above' and 'hidden'.
* Defaults to 'above'.
* - type: (string) The formatter to use. Defaults to the
* 'default_formatter' for the field type, specified in
* hook_field_info(). The default formatter will also be used if the
* requested formatter is not available.
* 'default_formatter' for the field type, specified in hook_field_info().
* The default formatter will also be used if the requested formatter is
* not available.
* - settings: (array) Settings specific to the formatter. Defaults to the
* formatter's default settings, specified in
* hook_field_formatter_info().
* formatter's default settings, specified in hook_field_formatter_info().
* - weight: (float) The weight to assign to the renderable element.
* Defaults to 0.
* @param $langcode
* (Optional) The language code the field values are to be shown in. The
* site's current language fallback logic will be applied when no values are
* available for given language code. If no language code is provided the
* available for the given language code. If no language code is provided the
* current language will be used.
*
* @return
* A renderable array for the field value.
*
@ -991,10 +1006,11 @@ function field_get_items($entity_type, $entity, $field_name, $langcode = NULL) {
}
/**
* Determine whether a field has any data.
* Determines whether a field has any data.
*
* @param $field
* A field structure.
*
* @return
* TRUE if the field has data for any entity; FALSE otherwise.
*/
@ -1012,12 +1028,12 @@ function field_has_data($field) {
}
/**
* Determine whether the user has access to a given field.
* Determines whether the user has access to a given field.
*
* @param string $op
* The operation to be performed. Possible values:
* - 'edit'
* - 'view'
* - edit
* - view
* @param array $field
* The full field structure array for the field on which the operation is to
* be performed. See field_info_field().
@ -1029,8 +1045,7 @@ function field_has_data($field) {
* (optional) The account to check, if not given use currently logged in user.
*
* @return
* TRUE if the operation is allowed;
* FALSE if the operation is denied.
* TRUE if the operation is allowed; FALSE if the operation is denied.
*/
function field_access($op, $field, $entity_type, $entity = NULL, $account = NULL) {
global $user;
@ -1050,13 +1065,14 @@ function field_access($op, $field, $entity_type, $entity = NULL, $account = NULL
}
/**
* Helper function to extract the bundle name of from a bundle object.
* Extracts the bundle name from a bundle object.
*
* @param $entity_type
* The type of $entity; e.g., 'node' or 'user'.
* @param $bundle
* The bundle object (or string if bundles for this entity type do not exist
* as standalone objects).
*
* @return
* The bundle name.
*/
@ -1189,8 +1205,8 @@ function template_process_field(&$variables, $hook) {
* So, if the body field on the article content type needs customization, a
* field--body--article.tpl.php file can be added within the theme's folder.
* Because it's a template, it will result in slightly more time needed to
* display that field, but it will not impact other fields, and therefore,
* is unlikely to cause a noticeable change in website performance. A very rough
* display that field, but it will not impact other fields, and therefore, is
* unlikely to cause a noticeable change in website performance. A very rough
* guideline is that if a page is being displayed with more than 100 fields and
* they are all themed with a template instead of a function, it can add up to
* 5% to the time it takes to display that page. This is a guideline only and
@ -1199,7 +1215,8 @@ function template_process_field(&$variables, $hook) {
*
* @param $variables
* An associative array containing:
* - label_hidden: A boolean indicating to show or hide the field label.
* - label_hidden: A boolean indicating whether to show or hide the field
* label.
* - title_attributes: A string containing the attributes for the title.
* - label: The label for the field.
* - content_attributes: A string containing the attributes for the content's

16
core/modules/field/field.multilingual.inc
View File

@ -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.
*/

4
core/modules/field/modules/field_sql_storage/field_sql_storage.install
View File

@ -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
*/

55
core/modules/field/modules/field_sql_storage/field_sql_storage.module
View File

@ -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);

2
core/modules/field/modules/number/number.install
View File

@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the number module.
* Install, update, and uninstall functions for the Number module.
*/
/**

4
core/modules/field/modules/number/number.module
View File

@ -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) {

55
core/modules/field/modules/options/options.module
View File

@ -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.
* @param $multiple
* TRUE if the field allows multiple values; FALSE otherwise.
* @param $required
* TRUE if a value is required for the field; FALSE otherwise.
* @param $has_value
* TRUE if a value is selected.
*
* @return
* An array of properties for the widget.
*/
function _options_properties($type, $multiple, $required, $has_value) {
$base = array(
@ -655,9 +667,12 @@ function _options_get_options($field, $instance, $properties, $entity_type, $ent
}
/**
* Sanitizes the options.
* Sanitizes the options recursively to support optgroups.
*
* The function is recursive to support optgroups.
* @param $options
* The option array.
* @param $properties
* An array containing the properties of the widget.
*/
function _options_prepare_options(&$options, $properties) {
foreach ($options as $value => $label) {
@ -678,6 +693,18 @@ function _options_prepare_options(&$options, $properties) {
/**
* Transforms stored field values into the format the widgets need.
*
* @param $items
* An array of stored field values.
* @param $options
* The options array.
* @param $column
* The field storage column of the field.
* @param $properties
* An array containing the properties of the widget.
*
* @return
* An array of values in the format used by widgets.
*/
function _options_storage_to_form($items, $options, $column, $properties) {
$items_transposed = options_array_transpose($items);
@ -694,6 +721,12 @@ function _options_storage_to_form($items, $options, $column, $properties) {
/**
* Transforms submitted form values into field storage format.
*
* @param $element
* The form element.
*
* @return
* An array of field values in field storage format.
*/
function _options_form_to_storage($element) {
$values = array_values((array) $element['#value']);
@ -725,13 +758,14 @@ function _options_form_to_storage($element) {
/**
* Manipulates a 2D array to reverse rows and columns.
*
* The default data storage for fields is delta first, column names second.
* This is sometimes inconvenient for field modules, so this function can be
* used to present the data in an alternate format.
* The default data storage for fields is delta first, column names second. This
* is sometimes inconvenient for field modules, so this function can be used to
* present the data in an alternate format.
*
* @param $array
* The array to be transposed. It must be at least two-dimensional, and
* the subarrays must all have the same keys or behavior is undefined.
* The array to be transposed. It must be at least two-dimensional, and the
* subarrays must all have the same keys or behavior is undefined.
*
* @return
* The transposed array.
*/
@ -790,9 +824,10 @@ function options_options_list($field, $instance, $entity_type, $entity) {
}
/**
* Returns HTML for the label for the empty value for options that are not required.
* Returns HTML for the label for the empty value for non-required options.
*
* The default theme will display N/A for a radio list and '- None -' for a select.
* The default theme will display N/A for a radio list and '- None -' for a
* select.
*
* @param $variables
* An associative array containing:

2
core/modules/field/modules/text/text.install
View File

@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the text module.
* Install, update, and uninstall functions for the Text module.
*/
/**

44
core/modules/field/modules/text/text.module
View File

@ -22,12 +22,12 @@ function text_help($path, $arg) {
* Implements hook_field_info().
*
* Field settings:
* - max_length: the maximum length for a varchar field.
* - max_length: The maximum length for a varchar field.
* Instance settings:
* - text_processing: whether text input filters should be used.
* - display_summary: whether the summary field should be displayed.
* When empty and not displayed the summary will take its value from the
* trimmed value of the main text field.
* - text_processing: Whether text input filters should be used.
* - display_summary: Whether the summary field should be displayed. When
* empty and not displayed the summary will take its value from the trimmed
* value of the main text field.
*/
function text_field_info() {
return array(
@ -112,8 +112,8 @@ function text_field_instance_settings_form($field, $instance) {
* Implements hook_field_validate().
*
* Possible error codes:
* - 'text_value_max_length': The value exceeds the maximum length.
* - 'text_summary_max_length': The summary exceeds the maximum length.
* - text_value_max_length: The value exceeds the maximum length.
* - text_summary_max_length: The summary exceeds the maximum length.
*/
function text_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
foreach ($items as $delta => $item) {
@ -144,9 +144,9 @@ function text_field_validate($entity_type, $entity, $field, $instance, $langcode
/**
* Implements hook_field_load().
*
* Where possible, generate the sanitized version of each field early so that
* it is cached in the field cache. This avoids looking up from the filter cache
* separately.
* Where possible, the function generates the sanitized version of each field
* early so that it is cached in the field cache. This avoids the need to look
* up the field in the filter cache separately.
*
* @see text_field_formatter_view()
*/
@ -302,14 +302,14 @@ function text_field_formatter_view($entity_type, $entity, $field, $instance, $la
* @param $instance
* The instance definition.
* @param $langcode
* The language associated to $item.
* The language associated with $item.
* @param $item
* The field value to sanitize.
* @param $column
* The column to sanitize (either 'value' or 'summary').
*
* @return
* The sanitized string.
* The sanitized string.
*/
function _text_sanitize($instance, $langcode, $item, $column) {
// If the value uses a cacheable text format, text_field_load() precomputes
@ -321,27 +321,25 @@ function _text_sanitize($instance, $langcode, $item, $column) {
}
/**
* Generate a trimmed, formatted version of a text field value.
* Generates a trimmed, formatted version of a text field value.
*
* If the end of the summary is not indicated using the <!--break--> delimiter
* then we generate the summary automatically, trying to end it at a sensible
* place such as the end of a paragraph, a line break, or the end of a
* sentence (in that order of preference).
* place such as the end of a paragraph, a line break, or the end of a sentence
* (in that order of preference).
*
* @param $text
* The content for which a summary will be generated.
* @param $format
* The format of the content.
* If the PHP filter is present and $text contains PHP code, we do not
* split it up to prevent parse errors.
* If the line break filter is present then we treat newlines embedded in
* $text as line breaks.
* The format of the content. If the PHP filter is present and $text contains
* PHP code, we do not split it up to prevent parse errors. If the line break
* filter is present then we treat newlines embedded in $text as line breaks.
* If the htmlcorrector filter is present, it will be run on the generated
* summary (if different from the incoming $text).
* @param $size
* The desired character length of the summary. If omitted, the default
* value will be used. Ignored if the special delimiter is present
* in $text.
* The desired character length of the summary. If omitted, the default value
* will be used. Ignored if the special delimiter is present in $text.
*
* @return
* The generated summary.
*/