diff options
Diffstat (limited to 'modules/field/field.crud.inc')
| -rw-r--r-- | modules/field/field.crud.inc | 23 |
1 files changed, 18 insertions, 5 deletions
diff --git a/modules/field/field.crud.inc b/modules/field/field.crud.inc index e1acdd53b..c4c79d79f 100644 --- a/modules/field/field.crud.inc +++ b/modules/field/field.crud.inc @@ -522,17 +522,30 @@ 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 following + * required array elements specify which field instance is being updated: * - 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 - * properties specified in $instance overwrite the existing values for - * the instance. + * The other array elements represent properties of the instance, and all + * properties must be specified or their default values will be used (except + * internal-use properties, which are assigned automatically). To avoid + * losing the previously stored properties of the instance when making a + * change, first load the instance with field_info_instance(), then override + * the values you want to override, and finally save using this function. + * Example: + * @code + * // Fetch an instance info array. + * $instance_info = field_info_instance($entity_type, $field_name, $bundle_name); + * // Change a single property in the instance definition. + * $instance_info['definition']['required'] = TRUE; + * // Write the changed definition back. + * field_update_instance($instance_info['definition']); + * @endcode * * @throws FieldException * + * @see field_info_instance() * @see field_create_instance() */ function field_update_instance($instance) { |