diff options
Diffstat (limited to 'modules/field/field.module')
| -rw-r--r-- | modules/field/field.module | 186 |
1 files changed, 185 insertions, 1 deletions
diff --git a/modules/field/field.module b/modules/field/field.module index e96bdb0ce..08ee9d594 100644 --- a/modules/field/field.module +++ b/modules/field/field.module @@ -38,7 +38,191 @@ require_once DRUPAL_ROOT . '/modules/field/field.form.inc'; * fields via a web browser as well as a wide and flexible variety of * data type, form element, and display format capabilities. * - * - @link field_structs Data structures: Field, Instance, Bundle @endlink. + * 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'. + * + * 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 assigned automatically + * by field_create_field(). + * - 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 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 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 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 field type. + * - 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 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 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. + * - 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. 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 are defined + * by modules that implement 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 storage backend is currently + * enabled, FALSE otherwise. + * - 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 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 + * - ... + * + * 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 |