From f3ed3283db182dfbbf35f5db077ebce2bc368bfe Mon Sep 17 00:00:00 2001 From: Angie Byron Date: Thu, 5 Feb 2009 03:42:58 +0000 Subject: #361683 follow-up by sun: Remove more windows line endings. --- modules/field/field.crud.inc | 1114 +++++++++++++++++++++--------------------- 1 file changed, 557 insertions(+), 557 deletions(-) (limited to 'modules/field/field.crud.inc') diff --git a/modules/field/field.crud.inc b/modules/field/field.crud.inc index e63838140..01f2743cd 100644 --- a/modules/field/field.crud.inc +++ b/modules/field/field.crud.inc @@ -1,558 +1,558 @@ -$field_name. - * - type (string) - * The type of the field, such as 'text' or 'image'. Field types - * are defined by modules that implement hook_field_into(). - * - cardinality (integer) - * The number of values the field can hold. Legal values are any - * positive integer or FIELD_CARDINALITY_UNLIMITED. - * - locked (integer) - * TODO: undefined. - * - 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. - * - 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. - * - * Field Instance objects are (currently) represented as an array of - * key/value pairs. The object properties are: - * - * @param array $instance: - * - field_name (string) - * The name of field attached by this instance. - * - 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. - * - weight (float) - * The order in which the field should be sorted relative - * to other fields when used with this bundle. The weight affects - * ordering in both forms (see field_attach_form()) and rendered output - * (see field_attach_view()). - * TODO - this should probably become a context setting so that - * the weight can be different in the form and in various other - * contexts. - * - 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. - * - 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(). - * - module (string, read-only) - * The name of the module that implements the widget type. - * - active (integer, read-only) - * TRUE if the module that implements the widget type is currently - * enabled, FALSE otherwise. - * - 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. - * - display (array) - * A sub-array of key/value pairs identifying display contexts - * and the way the field should be displayed in that context. - * TODO more work to do here. - * - (context_1) - * - label - * - exclude - * - type - * - settings - * - ... - * - module (internal) - * - (context 2) - * - ... - * - * TODO D7 : document max length for field types, widget types, - * formatter names... - */ -/** - * @} End of "defgroup field_structs". - */ - -/** - * @defgroup field_crud Field CRUD API - * @{ - * Create, update, and delete 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. - * - * The Field CRUD API uses - * @link field_structs Field API data structures @endlink. - */ - -/** - * Create a field. This function does not bind the field to any - * bundle; use field_create_instance for that. - * - * @param $field - * A field structure. The field_name and type properties are required. - * @throw - * FieldException - */ -function field_create_field($field) { - // Field name is required. - if (empty($field['field_name'])) { - throw new FieldException('Attempt to create an unnamed field.'); - } - // Field name cannot contain invalid characters. - if (preg_match('/[^a-z0-9_]/', $field['field_name'])) { - throw new FieldException('Attempt to create a field with invalid characters. Only alphanumeric characters and underscores are allowed.'); - } - - // TODO: check that field_name < 32 chars. - - // Check that the field type is known. - $field_type = field_info_field_types($field['type']); - if (!$field_type) { - throw new FieldException(t('Attempt to create a field of unknown type %type.', array('%type' => $field['type']))); - } - - // Ensure the field name is unique. We also check disabled or deleted fields. - // TODO : do we want specific messages when clashing with a disabled or inactive field ? - $prior_field = field_read_field($field['field_name'], array('include_inactive' => TRUE, 'include_deleted' => TRUE)); - if (!empty($prior_field)) { - throw new FieldException(t('Attempt to create field name %name which already exists.', array('%name' => $field['field_name']))); - } - - $field += array( - 'cardinality' => 1, - 'locked' => FALSE, - 'settings' => array(), - ); - $module = $field_type['module']; - // Create all per-field-type properties (needed here as long as we have - // settings that impact column definitions). - $field['settings'] += field_info_field_settings($field['type']); - $field['module'] = $module; - $field['active'] = 1; - $field['deleted'] = 0; - // Create the data table. We need to populate the field columns, even though - // we don't actually store them. - $field['columns'] = (array) module_invoke($field['module'], 'field_columns', $field); - module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_create_field', $field); - - drupal_write_record('field_config', $field); - - // Clear caches - field_cache_clear(TRUE); -} - -/** - * Read a single field record directly from the database. Generally, - * you should use the field_info_field() instead. - * - * @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 or has been deleted. Setting - * $include_additional['include_inactive'] or - * $include_additional['include_deleted'] to TRUE will override this - * behavior. - * @return - * A field structure, or FALSE. - */ -function field_read_field($field_name, $include_additional = array()) { - $fields = field_read_fields(array('field_name' => $field_name), $include_additional); - return $fields ? current($fields) : FALSE; -} - -/** - * Read in fields that match an array of conditions. - * - * @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 - * $include_additional['include_inactive'] or - * $include_additional['include_deleted'] to TRUE will override this - * behavior. - * @return - * An array of fields matching $params. - */ -function field_read_fields($params = array(), $include_additional = array()) { - $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC)); - $query->fields('fc'); - - // Turn the conditions into a query. - foreach ($params as $key => $value) { - $query->condition($key, $value); - } - if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) { - $query->condition('fc.active', 1); - } - if (!isset($include_additional['include_deleted']) || !$include_additional['include_deleted']) { - $query->condition('fc.deleted', 0); - } - - $fields = array(); - $results = $query->execute(); - foreach ($results as $field) { - // drupal_write_record() writes an empty string for empty arrays. - $field['settings'] = $field['settings'] ? unserialize($field['settings']) : array(); - - module_invoke_all('field_read_field', $field); - - // Populate storage columns. - $field['columns'] = (array) module_invoke($field['module'], 'field_columns', $field); - - $fields[$field['field_name']] = $field; - } - return $fields; -} - -/** - * Mark a field for deletion, including all its instances and all data - * associated with it. - * - * @param $field_name - * The field name to delete. - */ -function field_delete_field($field_name) { - // Mark the field for deletion. - db_update('field_config') - ->fields(array('deleted' => 1)) - ->condition('field_name', $field_name) - ->execute(); - - // Mark any instances of the field for deletion. - db_update('field_config_instance') - ->fields(array('deleted' => 1)) - ->condition('field_name', $field_name) - ->execute(); - module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_delete_field', $field_name); - // Clear the cache. - field_cache_clear(TRUE); -} - -/** - * Creates an instance of a field, binding it to a bundle. - * - * @param $instance - * A field instance structure. The field_name and bundle properties - * are required. - * @throw - * FieldException - */ -function field_create_instance($instance) { - // Check that the specified field exists. - $field = field_read_field($instance['field_name']); - if (empty($field)) { - throw new FieldException("Attempt to create an instance of a field that doesn't exist."); - } - - // TODO: Check that the specifed bundle exists. - - // TODO: Check that the widget type is known and can handle the field type ? - // TODO: Check that the formatters are known and can handle the field type ? - // TODO: Check that the display build modes are known for the object type ? - // Those checks should probably happen in _field_write_instance() ? - // Problem : this would mean that a UI module cannot update an instance with a disabled formatter. - - // Ensure the field instance is unique. - // TODO : do we want specific messages when clashing with a disabled or inactive instance ? - $prior_instance = field_read_instance($instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE, 'include_deleted' => TRUE)); - if (!empty($prior_instance)) { - throw new FieldException('Attempt to create a field instance which already exists.'); - } - - _field_write_instance($instance); - - module_invoke_all('field_create_instance', $instance); - - // Clear caches - field_cache_clear(); - return FALSE; -} - -/* - * Update an instance of a field. - * - * @param $instance - * An associative array represeting an instance structure. The required - * keys and values are: - * field_name: The name of an existing field. - * bundle: The bundle this field belongs to. - * Any other properties specified in $instance overwrite the - * existing values for the instance. - * @throw - * FieldException - * @see field_create_instance() - */ -function field_update_instance($instance) { - // Check that the specified field exists. - $field = field_read_field($instance['field_name']); - if (empty($field)) { - throw new FieldException("Attempt to update an instance of a nonexistent field."); - } - - // Check that the field instance exists (even if it is inactive, since we - // want to be able to replace inactive widgets with new ones). - $prior_instance = field_read_instance($instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE)); - if (empty($prior_instance)) { - throw new FieldException("Attempt to update a field instance that doesn't exist."); - } - - _field_write_instance($instance, TRUE); - - // Clear caches. - field_cache_clear(); -} - -/** - * Store an instance record in the field configuration database. - * - * @param $instance - * An instance structure. - * @param $update - * Whether this is a new or existing instance. - */ -function _field_write_instance($instance, $update = FALSE) { - $field = field_read_field($instance['field_name']); - $field_type = field_info_field_types($field['type']); - - // Set defaults. - $instance += array( - 'settings' => array(), - 'display' => array(), - 'widget' => array(), - 'required' => FALSE, - 'label' => $instance['field_name'], - 'description' => '', - 'weight' => 0, - 'deleted' => 0, - ); - - // Set default instance settings. - $instance['settings'] += field_info_instance_settings($field['type']); - - // Set default widget and settings. - $instance['widget'] += array( - // TODO: what if no 'default_widget' specified ? - 'type' => $field_type['default_widget'], - 'settings' => array(), - ); - // Check widget module. - $widget_type = field_info_widget_types($instance['widget']['type']); - $widget_module = $widget_type['module']; - $widget_active = module_exists($widget_module); - $instance['widget']['settings'] += field_info_widget_settings($instance['widget']['type']); - $instance['widget']['module'] = $widget_module; - $instance['widget']['active'] = $widget_active; - - // Make sure there is at least display info for the 'full' context. - $instance['display'] += array( - 'full' => array(), - ); - // Set default display settings for each context. - foreach ($instance['display'] as $context => $display) { - $instance['display'][$context] += array( - 'label' => 'above', - 'exclude' => 0, - // TODO: what if no 'default_formatter' specified ? - 'type' => $field_type['default_formatter'], - 'settings' => array(), - ); - $formatter_type = field_info_formatter_types($instance['display'][$context]['type']); - // TODO : 'hidden' will raise PHP warnings. - $instance['display'][$context]['module'] = $formatter_type['module']; - $instance['display'][$context]['settings'] += field_info_formatter_settings($instance['display'][$context]['type']); - } - - // Create $data to contain everything from $instance that does not - // have its own column, and thus will be stored serialized. - $data = $instance; - unset($data['field_name'], $data['bundle'], $data['widget']['type'], $data['weight'], $data['deleted']); - - $record = array( - 'field_name' => $instance['field_name'], - 'bundle' => $instance['bundle'], - 'widget_type' => $instance['widget']['type'], - 'widget_module' => $widget_module, - 'widget_active' => $widget_active, - 'weight' => $instance['weight'], - 'data' => $data, - 'deleted' => $instance['deleted'], - ); - // We need to tell drupal_update_record() the primary keys to trigger an - // update. - $primary_keys = $update ? array('field_name', 'bundle') : array(); - drupal_write_record('field_config_instance', $record, $primary_keys); -} - -/** - * Read a single instance record directly from the database. Generally, - * you should use the field_info_instance() instead. - * - * @param $field_name - * The field name to read. - * @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 - * is inactive or has been deleted. Setting - * $include_additional['include_inactive'] or - * $include_additional['include_deleted'] to TRUE will override this - * behavior. - * @return - * An instance structure, or FALSE. - */ -function field_read_instance($field_name, $bundle, $include_additional = array()) { - $instances = field_read_instances(array('field_name' => $field_name, 'bundle' => $bundle), $include_additional); - return $instances ? current($instances) : FALSE; -} - -/** - * Read 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. - * @param $include_additional - * The default behavior of this function is to not return field - * instances that are inactive or have been marked deleted. Setting - * $include_additional['include_inactive'] or - * $include_additional['include_deleted'] to TRUE will override this - * behavior. - * @return - * An array of instances matching the arguments. - */ -function field_read_instances($params = array(), $include_additional = array()) { - $query = db_select('field_config_instance', 'fci', array('fetch' => PDO::FETCH_ASSOC)); - $query->join('field_config', 'fc', 'fc.field_name = fci.field_name'); - $query->fields('fci'); - #$query->fields('fc', array('type')); - - // Turn the conditions into a query. - foreach ($params as $key => $value) { - $query->condition('fci.' . $key, $value); - } - $query->condition('fc.active', 1); - if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) { - $query->condition('fci.widget_active', 1); - } - if (!isset($include_additional['include_deleted']) || !$include_additional['include_deleted']) { - $query->condition('fc.deleted', 0); - $query->condition('fci.deleted', 0); - } - - $instances = array(); - $results = $query->execute(); - - foreach ($results as $record) { - $instance = unserialize($record['data']); - $instance['field_name'] = $record['field_name']; - $instance['bundle'] = $record['bundle']; - $instance['weight'] = $record['weight']; - $instance['deleted'] = $record['deleted']; - $instance['widget']['type'] = $record['widget_type']; - $instance['widget']['module'] = $record['widget_module']; - $instance['widget']['active'] = $record['widget_active']; - - // TODO D7 : Set default widget settings, default instance settings, default display settings. - // (the modules that defined them might have changed since the instance was last saved). - - module_invoke_all('field_read_instance', $instance); - $instances[] = $instance; - } - return $instances; -} - -/** - * Mark a field instance for deletion, including all data associated with - * it. - * - * @param $field_name - * The name of the field whose instance will be deleted. - * @param $bundle - * The bundle for the instance which will be deleted. - */ -function field_delete_instance($field_name, $bundle) { - // Mark the field instance for deletion. - db_update('field_config_instance') - ->fields(array('deleted' => 1)) - ->condition('field_name', $field_name) - ->condition('bundle', $bundle) - ->execute(); - - // Mark all data associated with the field for deletion. - module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_delete_instance', $field_name, $bundle); - // Clear the cache. - field_cache_clear(); -} - -/** - * @} End of "defgroup field_crud". +$field_name. + * - type (string) + * The type of the field, such as 'text' or 'image'. Field types + * are defined by modules that implement hook_field_into(). + * - cardinality (integer) + * The number of values the field can hold. Legal values are any + * positive integer or FIELD_CARDINALITY_UNLIMITED. + * - locked (integer) + * TODO: undefined. + * - 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. + * - 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. + * + * Field Instance objects are (currently) represented as an array of + * key/value pairs. The object properties are: + * + * @param array $instance: + * - field_name (string) + * The name of field attached by this instance. + * - 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. + * - weight (float) + * The order in which the field should be sorted relative + * to other fields when used with this bundle. The weight affects + * ordering in both forms (see field_attach_form()) and rendered output + * (see field_attach_view()). + * TODO - this should probably become a context setting so that + * the weight can be different in the form and in various other + * contexts. + * - 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. + * - 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(). + * - module (string, read-only) + * The name of the module that implements the widget type. + * - active (integer, read-only) + * TRUE if the module that implements the widget type is currently + * enabled, FALSE otherwise. + * - 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. + * - display (array) + * A sub-array of key/value pairs identifying display contexts + * and the way the field should be displayed in that context. + * TODO more work to do here. + * - (context_1) + * - label + * - exclude + * - type + * - settings + * - ... + * - module (internal) + * - (context 2) + * - ... + * + * TODO D7 : document max length for field types, widget types, + * formatter names... + */ +/** + * @} End of "defgroup field_structs". + */ + +/** + * @defgroup field_crud Field CRUD API + * @{ + * Create, update, and delete 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. + * + * The Field CRUD API uses + * @link field_structs Field API data structures @endlink. + */ + +/** + * Create a field. This function does not bind the field to any + * bundle; use field_create_instance for that. + * + * @param $field + * A field structure. The field_name and type properties are required. + * @throw + * FieldException + */ +function field_create_field($field) { + // Field name is required. + if (empty($field['field_name'])) { + throw new FieldException('Attempt to create an unnamed field.'); + } + // Field name cannot contain invalid characters. + if (preg_match('/[^a-z0-9_]/', $field['field_name'])) { + throw new FieldException('Attempt to create a field with invalid characters. Only alphanumeric characters and underscores are allowed.'); + } + + // TODO: check that field_name < 32 chars. + + // Check that the field type is known. + $field_type = field_info_field_types($field['type']); + if (!$field_type) { + throw new FieldException(t('Attempt to create a field of unknown type %type.', array('%type' => $field['type']))); + } + + // Ensure the field name is unique. We also check disabled or deleted fields. + // TODO : do we want specific messages when clashing with a disabled or inactive field ? + $prior_field = field_read_field($field['field_name'], array('include_inactive' => TRUE, 'include_deleted' => TRUE)); + if (!empty($prior_field)) { + throw new FieldException(t('Attempt to create field name %name which already exists.', array('%name' => $field['field_name']))); + } + + $field += array( + 'cardinality' => 1, + 'locked' => FALSE, + 'settings' => array(), + ); + $module = $field_type['module']; + // Create all per-field-type properties (needed here as long as we have + // settings that impact column definitions). + $field['settings'] += field_info_field_settings($field['type']); + $field['module'] = $module; + $field['active'] = 1; + $field['deleted'] = 0; + // Create the data table. We need to populate the field columns, even though + // we don't actually store them. + $field['columns'] = (array) module_invoke($field['module'], 'field_columns', $field); + module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_create_field', $field); + + drupal_write_record('field_config', $field); + + // Clear caches + field_cache_clear(TRUE); +} + +/** + * Read a single field record directly from the database. Generally, + * you should use the field_info_field() instead. + * + * @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 or has been deleted. Setting + * $include_additional['include_inactive'] or + * $include_additional['include_deleted'] to TRUE will override this + * behavior. + * @return + * A field structure, or FALSE. + */ +function field_read_field($field_name, $include_additional = array()) { + $fields = field_read_fields(array('field_name' => $field_name), $include_additional); + return $fields ? current($fields) : FALSE; +} + +/** + * Read in fields that match an array of conditions. + * + * @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 + * $include_additional['include_inactive'] or + * $include_additional['include_deleted'] to TRUE will override this + * behavior. + * @return + * An array of fields matching $params. + */ +function field_read_fields($params = array(), $include_additional = array()) { + $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC)); + $query->fields('fc'); + + // Turn the conditions into a query. + foreach ($params as $key => $value) { + $query->condition($key, $value); + } + if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) { + $query->condition('fc.active', 1); + } + if (!isset($include_additional['include_deleted']) || !$include_additional['include_deleted']) { + $query->condition('fc.deleted', 0); + } + + $fields = array(); + $results = $query->execute(); + foreach ($results as $field) { + // drupal_write_record() writes an empty string for empty arrays. + $field['settings'] = $field['settings'] ? unserialize($field['settings']) : array(); + + module_invoke_all('field_read_field', $field); + + // Populate storage columns. + $field['columns'] = (array) module_invoke($field['module'], 'field_columns', $field); + + $fields[$field['field_name']] = $field; + } + return $fields; +} + +/** + * Mark a field for deletion, including all its instances and all data + * associated with it. + * + * @param $field_name + * The field name to delete. + */ +function field_delete_field($field_name) { + // Mark the field for deletion. + db_update('field_config') + ->fields(array('deleted' => 1)) + ->condition('field_name', $field_name) + ->execute(); + + // Mark any instances of the field for deletion. + db_update('field_config_instance') + ->fields(array('deleted' => 1)) + ->condition('field_name', $field_name) + ->execute(); + module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_delete_field', $field_name); + // Clear the cache. + field_cache_clear(TRUE); +} + +/** + * Creates an instance of a field, binding it to a bundle. + * + * @param $instance + * A field instance structure. The field_name and bundle properties + * are required. + * @throw + * FieldException + */ +function field_create_instance($instance) { + // Check that the specified field exists. + $field = field_read_field($instance['field_name']); + if (empty($field)) { + throw new FieldException("Attempt to create an instance of a field that doesn't exist."); + } + + // TODO: Check that the specifed bundle exists. + + // TODO: Check that the widget type is known and can handle the field type ? + // TODO: Check that the formatters are known and can handle the field type ? + // TODO: Check that the display build modes are known for the object type ? + // Those checks should probably happen in _field_write_instance() ? + // Problem : this would mean that a UI module cannot update an instance with a disabled formatter. + + // Ensure the field instance is unique. + // TODO : do we want specific messages when clashing with a disabled or inactive instance ? + $prior_instance = field_read_instance($instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE, 'include_deleted' => TRUE)); + if (!empty($prior_instance)) { + throw new FieldException('Attempt to create a field instance which already exists.'); + } + + _field_write_instance($instance); + + module_invoke_all('field_create_instance', $instance); + + // Clear caches + field_cache_clear(); + return FALSE; +} + +/* + * Update an instance of a field. + * + * @param $instance + * An associative array represeting an instance structure. The required + * keys and values are: + * field_name: The name of an existing field. + * bundle: The bundle this field belongs to. + * Any other properties specified in $instance overwrite the + * existing values for the instance. + * @throw + * FieldException + * @see field_create_instance() + */ +function field_update_instance($instance) { + // Check that the specified field exists. + $field = field_read_field($instance['field_name']); + if (empty($field)) { + throw new FieldException("Attempt to update an instance of a nonexistent field."); + } + + // Check that the field instance exists (even if it is inactive, since we + // want to be able to replace inactive widgets with new ones). + $prior_instance = field_read_instance($instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE)); + if (empty($prior_instance)) { + throw new FieldException("Attempt to update a field instance that doesn't exist."); + } + + _field_write_instance($instance, TRUE); + + // Clear caches. + field_cache_clear(); +} + +/** + * Store an instance record in the field configuration database. + * + * @param $instance + * An instance structure. + * @param $update + * Whether this is a new or existing instance. + */ +function _field_write_instance($instance, $update = FALSE) { + $field = field_read_field($instance['field_name']); + $field_type = field_info_field_types($field['type']); + + // Set defaults. + $instance += array( + 'settings' => array(), + 'display' => array(), + 'widget' => array(), + 'required' => FALSE, + 'label' => $instance['field_name'], + 'description' => '', + 'weight' => 0, + 'deleted' => 0, + ); + + // Set default instance settings. + $instance['settings'] += field_info_instance_settings($field['type']); + + // Set default widget and settings. + $instance['widget'] += array( + // TODO: what if no 'default_widget' specified ? + 'type' => $field_type['default_widget'], + 'settings' => array(), + ); + // Check widget module. + $widget_type = field_info_widget_types($instance['widget']['type']); + $widget_module = $widget_type['module']; + $widget_active = module_exists($widget_module); + $instance['widget']['settings'] += field_info_widget_settings($instance['widget']['type']); + $instance['widget']['module'] = $widget_module; + $instance['widget']['active'] = $widget_active; + + // Make sure there is at least display info for the 'full' context. + $instance['display'] += array( + 'full' => array(), + ); + // Set default display settings for each context. + foreach ($instance['display'] as $context => $display) { + $instance['display'][$context] += array( + 'label' => 'above', + 'exclude' => 0, + // TODO: what if no 'default_formatter' specified ? + 'type' => $field_type['default_formatter'], + 'settings' => array(), + ); + $formatter_type = field_info_formatter_types($instance['display'][$context]['type']); + // TODO : 'hidden' will raise PHP warnings. + $instance['display'][$context]['module'] = $formatter_type['module']; + $instance['display'][$context]['settings'] += field_info_formatter_settings($instance['display'][$context]['type']); + } + + // Create $data to contain everything from $instance that does not + // have its own column, and thus will be stored serialized. + $data = $instance; + unset($data['field_name'], $data['bundle'], $data['widget']['type'], $data['weight'], $data['deleted']); + + $record = array( + 'field_name' => $instance['field_name'], + 'bundle' => $instance['bundle'], + 'widget_type' => $instance['widget']['type'], + 'widget_module' => $widget_module, + 'widget_active' => $widget_active, + 'weight' => $instance['weight'], + 'data' => $data, + 'deleted' => $instance['deleted'], + ); + // We need to tell drupal_update_record() the primary keys to trigger an + // update. + $primary_keys = $update ? array('field_name', 'bundle') : array(); + drupal_write_record('field_config_instance', $record, $primary_keys); +} + +/** + * Read a single instance record directly from the database. Generally, + * you should use the field_info_instance() instead. + * + * @param $field_name + * The field name to read. + * @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 + * is inactive or has been deleted. Setting + * $include_additional['include_inactive'] or + * $include_additional['include_deleted'] to TRUE will override this + * behavior. + * @return + * An instance structure, or FALSE. + */ +function field_read_instance($field_name, $bundle, $include_additional = array()) { + $instances = field_read_instances(array('field_name' => $field_name, 'bundle' => $bundle), $include_additional); + return $instances ? current($instances) : FALSE; +} + +/** + * Read 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. + * @param $include_additional + * The default behavior of this function is to not return field + * instances that are inactive or have been marked deleted. Setting + * $include_additional['include_inactive'] or + * $include_additional['include_deleted'] to TRUE will override this + * behavior. + * @return + * An array of instances matching the arguments. + */ +function field_read_instances($params = array(), $include_additional = array()) { + $query = db_select('field_config_instance', 'fci', array('fetch' => PDO::FETCH_ASSOC)); + $query->join('field_config', 'fc', 'fc.field_name = fci.field_name'); + $query->fields('fci'); + #$query->fields('fc', array('type')); + + // Turn the conditions into a query. + foreach ($params as $key => $value) { + $query->condition('fci.' . $key, $value); + } + $query->condition('fc.active', 1); + if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) { + $query->condition('fci.widget_active', 1); + } + if (!isset($include_additional['include_deleted']) || !$include_additional['include_deleted']) { + $query->condition('fc.deleted', 0); + $query->condition('fci.deleted', 0); + } + + $instances = array(); + $results = $query->execute(); + + foreach ($results as $record) { + $instance = unserialize($record['data']); + $instance['field_name'] = $record['field_name']; + $instance['bundle'] = $record['bundle']; + $instance['weight'] = $record['weight']; + $instance['deleted'] = $record['deleted']; + $instance['widget']['type'] = $record['widget_type']; + $instance['widget']['module'] = $record['widget_module']; + $instance['widget']['active'] = $record['widget_active']; + + // TODO D7 : Set default widget settings, default instance settings, default display settings. + // (the modules that defined them might have changed since the instance was last saved). + + module_invoke_all('field_read_instance', $instance); + $instances[] = $instance; + } + return $instances; +} + +/** + * Mark a field instance for deletion, including all data associated with + * it. + * + * @param $field_name + * The name of the field whose instance will be deleted. + * @param $bundle + * The bundle for the instance which will be deleted. + */ +function field_delete_instance($field_name, $bundle) { + // Mark the field instance for deletion. + db_update('field_config_instance') + ->fields(array('deleted' => 1)) + ->condition('field_name', $field_name) + ->condition('bundle', $bundle) + ->execute(); + + // Mark all data associated with the field for deletion. + module_invoke(variable_get('field_storage_module', 'field_sql_storage'), 'field_storage_delete_instance', $field_name, $bundle); + // Clear the cache. + field_cache_clear(); +} + +/** + * @} End of "defgroup field_crud". */ \ No newline at end of file -- cgit v1.2.3