diff options
| -rw-r--r-- | modules/field/field.module | 280 |
1 files changed, 125 insertions, 155 deletions
diff --git a/modules/field/field.module b/modules/field/field.module index 2625742d4..9b7f8194a 100644 --- a/modules/field/field.module +++ b/modules/field/field.module @@ -60,166 +60,136 @@ require_once DRUPAL_ROOT . '/modules/field/field.form.inc'; * 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. + * - 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. + * 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 - * - ... + * - 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(). |