diff --git a/core/modules/field/field.crud.inc b/core/modules/field/field.crud.inc index 6e2eeb3..a3a8e44 100644 --- a/core/modules/field/field.crud.inc +++ b/core/modules/field/field.crud.inc @@ -238,16 +238,6 @@ function field_delete_field($field_name) { * - type: the default widget specified in hook_field_info(). * - settings: each omitted setting is given the default value specified in * hook_field_widget_info(). - * - display: - * Settings for the 'default' view mode will be added if not present, and - * each view mode in the definition will be completed with the following - * default values: - * - label: 'above' - * - type: the default formatter specified in hook_field_info(). - * - settings: each omitted setting is given the default value specified in - * hook_field_formatter_info(). - * View modes not present in the definition are left empty, and the field - * will not be displayed in this mode. * * @return \Drupal\field\Plugin\Core\Entity\FieldInstance * The field instance entity. diff --git a/core/modules/field/field.module b/core/modules/field/field.module index be3a649..a5b02bc 100644 --- a/core/modules/field/field.module +++ b/core/modules/field/field.module @@ -49,88 +49,6 @@ * 'subtitle' and 'photo' fields because they are both attached to the 'node' * bundle 'article'. * - * @todo Move this to FieldInstance.php - * 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 - * field_create_instance(). - * - 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 - * 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 - * 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 - * will provide a default value. - * - 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 - * 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 - * 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 - * in entity edit forms. - * - 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 - * 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. - * - ... - * - other_mode: - * - ... - * - * The (default) render arrays produced for field instances are documented at - * field_attach_view(). - * - * 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 diff --git a/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/Field.php b/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/Field.php index b3cd7fa..c92d80a 100644 --- a/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/Field.php +++ b/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/Field.php @@ -36,12 +36,12 @@ class Field extends ConfigEntityBase implements \ArrayAccess { /** * The field ID (machine name). * - * Example: body, field_main_image. - * * This is the name of the property under which the field values are placed in * an entity : $entity-{>$field_id}. Maximum length is 32 characters. For * fields created through Field UI, this includes the 'field_' prefix. * + * Example: body, field_main_image. + * * @var string */ public $id; @@ -58,10 +58,10 @@ class Field extends ConfigEntityBase implements \ArrayAccess { /** * The field type. * - * Example: text, number_integer. - * * Field types are defined by modules that implement hook_field_info(). * + * Example: text, number_integer. + * * @var string */ public $type; @@ -84,7 +84,7 @@ class Field extends ConfigEntityBase implements \ArrayAccess { * Field-type specific settings. * * An array of key/value pairs, The keys and default values are defined by the - * field type in hook_field_info(). + * field type in the 'settings' entry of hook_field_info(). * * @var array */ @@ -141,8 +141,8 @@ class Field extends ConfigEntityBase implements \ArrayAccess { * - type: (string) The storage backend used by the field. Storage backends * are defined by modules that implement hook_field_storage_info(). * - settings: (array) A sub-array of key/value pairs of settings. The keys - * and default values are defined by the storage backend in its - * hook_field_storage_info(). + * and default values are defined by the storage backend in the 'settings' + * entry of hook_field_storage_info(). * - 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 diff --git a/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/FieldInstance.php b/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/FieldInstance.php index 24147c4..ca5afbf 100644 --- a/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/FieldInstance.php +++ b/core/modules/field/lib/Drupal/field/Plugin/Core/Entity/FieldInstance.php @@ -31,7 +31,11 @@ class FieldInstance extends ConfigEntityBase implements \ArrayAccess { /** - * The field ID (config name). + * The instance ID (machine name). + * + * The ID consists of 3 parts: the entity type, bundle and the field name. + * + * Example: node.article.body, user.user.field_main_image. * * @var string */ @@ -40,19 +44,21 @@ class FieldInstance extends ConfigEntityBase implements \ArrayAccess { /** * The instance UUID. * + * This is assigned automatically when the instance is created. + * * @var string */ public $uuid; /** - * The field UUID. + * The UUID of the field attached to the bundle by this instance. * * @var string */ public $field_uuid; /** - * The field name. + * The name of the field attached to the bundle by this instance. * @todo Revisit that in favor of a getField() method. * * @var string @@ -60,74 +66,145 @@ class FieldInstance extends ConfigEntityBase implements \ArrayAccess { public $field_name; /** - * The instance entity type. + * The name of the entity type the instance is attached to. * * @var string */ public $entity_type; /** - * The instance bundle. + * The name of the bundle the instance is attached to. * * @var string */ public $bundle; /** - * The instance label. + * The human-readable label for the instance. + * + * This will be used as the title of Form API elements for the field in entity + * edit forms, or as the label for the field values in displayed entities. * * @var string */ public $label; /** - * Default value. + * The instance description. * - * @var array - */ - public $default_value; - - /** - * Default value function + * 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 in entity edit forms. * * @var string */ - public $default_value_function; + public $description; /** - * The instance settings. + * Field-type specific settings. + * + * An array of key/value pairs. The keys and default values are defined by the + * field type in the 'instance_settings' entry of hook_field_info(). * * @var array */ public $settings; /** - * The instance widget settings. + * Flag indicating whether the field is required. + * + * TRUE if a value for this field is required when used with this bundle, + * FALSE otherwise. Currently, required-ness is only enforced at the Form API + * level in entity edit forms, not during direct API saves. + * + * @var bool + */ + public $required; + + /** + * Default field value. + * + * The default value is used when an entity is created, either: + * - through an entity creation form; the form elements for the field are + * prepolulated with the default value. + * - through direct API calls (i.e. $entity->save()); the default value is + * added if the $entity object provides no explicit entry (actual values or + * "the field is empty") for the field. + * + * The default value is expressed as a numerically indexed array of items, + * each item being an array of key/value pairs matching the set of 'columns' + * defined by the "field schema" for the field type, as exposed in + * hook_field_schema(). If the number of items exceeds the cardinality of the + * field, extraneous items will be ignored. + * + * This property is overlooked if the $default_value_function is non-empty. + * + * Example for a number_integer field: + * @code + * array( + * array('value' => 1), + * array('value' => 2), + * ) + * @endcode * * @var array */ - public $widget; + public $default_value; /** - * The instance description. + * The name of a callback function that return default values. + * + * The function will be called with the following arguments: + * - \Drupal\Core\Entity\EntityInterface $entity + * The entity being created. + * - \Drupal\field\Plugin\Core\Entity\Field $field + * The field object. + * - \Drupal\field\Plugin\Core\Entity\FieldInstance $instance + * The field instance object. + * - string $langcode + * The language of the entity being created. + * It should return an array of default values, in the same format as the + * $default_value property. + * + * This property takes precedence on the list of fixed values specified in the + * $default_value property. * * @var string */ - public $description; + public $default_value_function; /** - * The instance deleted state. + * The widget definition. * - * @var bool + * An array of key/value pairs identifying the Form API input widget for + * the field when used by this bundle. + * - type: (string) The plugin ID of the widget, such as text_textfield. + * - settings: (array) A sub-array of key/value pairs of settings. The keys + * and default values are defined by the widget plugin in the 'settings' + * entry of its "plugin definition" (typycally plugin class annotations). + * - 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 provides the + * widget plugin. + * + * @var array */ - public $deleted; + public $widget; /** - * The instance required state. + * Flag indicating whether the instance is deleted. + * + * The delete() method marks the instance as "deleted" and removes the + * corresponding entry from the config storage, but keeps its definition in + * the state storage while field data is purged by a separate + * garbage-collection process. + * + * Deleted instances stay out of the regular entity lifecycle (notably, their + * values are not populated in loaded entities, and are not saved back). * * @var bool */ - public $required; + public $deleted; /** * The widget plugin used for this instance.