DrupalAPI.de

1. drupal
   1. drupal7

Creates an instance of a field, binding it to a bundle.

@throw FieldException

Übergabeparameter

$instance A field instance structure. The field_name and bundle properties are required. Other properties, if omitted, will be given the following default values:

• label: the field name
• description: empty string
• weight: 0
• required: FALSE
• default_value_function: empty string
• settings: each omitted setting is given the default value specified in hook_field_info().
• widget:
  • 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 'full' build mode will be added, and each build mode will be completed with the follwong default values:
  • label: 'above'
  • exclude: FALSE TODO This is subject to change, see: http://drupal.org/node/367215
  • type: the default formatter specified in hook_field_info().
  • settings: each omitted setting is given the default value specified in hook_field_formatter_info().

Verwandte Themen

Field CRUD API

Create, update, and delete Field API fields, bundles, and instances.

Code

modules/field/field.crud.inc, line 397

<?php
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.");
  }

  // Set the field id.
  $instance['field_id'] = $field['id'];

  // 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);

  // Clear caches
  field_cache_clear();

  // Invoke external hooks after the cache is cleared for API consistency.
  module_invoke_all('field_create_instance', $instance);

  return FALSE;
}
?>