function content_field_instance_create in Content Construction Kit (CCK) 6.2

Same name and namespace in other branches

1. 5 content_crud.inc \content_field_instance_create()
2. 6.3 includes/content.crud.inc \content_field_instance_create()
3. 6 includes/content.crud.inc \content_field_instance_create()

Create a new field instance.

Parameters

$field: An array of properties to create the field with, input either in the field => widget format used by the content module or as an array of form values.

Required values:

• field_name, the name of the field to be created
• type_name, the content type of the instance to be created

If there is no prior instance to create this from, we also need:

• type, the type of field to create
• widget_type, the type of widget to use

$rebuild: TRUE to clear content type caches and rebuild menu (default). FALSE allows the caller to process several fields at a time quickly, but then the caller is reponsible to clear content type caches and rebuild menu as soon as all fields have been processed. For example:

// Create several fields at a time.
foreach ($fields as $field) {
  content_field_instance_create($field, FALSE);
}

// Clear caches and rebuild menu.
content_clear_type_cache(TRUE);
menu_rebuild();

See also

content_clear_type_cache()

menu_rebuild()

4 calls to content_field_instance_create()

ContentCrudTestCase::createField in tests/content.crud.test

Creates a field instance with a predictable name. Also makes all future calls to functions which take an optional field use this one as the default.

ContentCrudTestCase::shareField in tests/content.crud.test

Makes a copy of a field instance on a different content type, effectively sharing the field with a new content type. Also makes all future calls to functions which take an optional field use the shared one as the default.

content_copy_import_form_submit in modules/content_copy/content_copy.module

Submit handler for import form. For each submitted field: 1) add new field to the database 2) execute the imported field macro to update the settings to the imported values

content_field_overview_form_submit in includes/content.admin.inc

File

includes/content.crud.inc, line 209

Create/Read/Update/Delete functions for CCK-defined object types.

Code

function content_field_instance_create($field, $rebuild = TRUE) {
  include_once './' . drupal_get_path('module', 'content') . '/includes/content.admin.inc';
  $form_values = $field;
  $field = content_field_instance_expand($field);

  // If there are prior instances, fill out missing values from the prior values,
  // otherwise get missing values from default values.
  $prior_instances = content_field_instance_read(array(
    'field_name' => $field['field_name'],
  ));
  if (!empty($prior_instances) && is_array($prior_instances)) {
    $prev_field = content_field_instance_expand($prior_instances[0]);

    // Weight, label, and description may have been forced into the $field
    // by content_field_instance_expand(). If there is a previous instance to
    // get these values from and there was no value supplied originally, use
    // the previous value.
    $field['widget']['weight'] = isset($form_values['weight']) ? $form_values['weight'] : $prev_field['widget']['weight'];
    $field['widget']['label'] = isset($form_values['label']) ? $form_values['label'] : $prev_field['widget']['label'];
    $field['widget']['description'] = isset($form_values['description']) ? $form_values['description'] : $prev_field['widget']['description'];
  }
  else {
    $prev_field = array(
      'widget' => array(),
    );
  }

  // If we have a field type, we can build default values for this field type.
  $default_values = array(
    'widget' => array(),
  );
  if (isset($field['type'])) {
    $default_values = content_field_default_values($field['type']);
    $default_instance_values = content_instance_default_values($field['field_name'], $field['type_name'], $field['widget']['type']);
    $default_values = content_field_instance_expand(array_merge($default_values, $default_instance_values));
  }

  // Merge default values, previous values, and current values to create
  // a complete field array.
  $widget = array_merge($default_values['widget'], $prev_field['widget'], $field['widget']);
  $field = array_merge($default_values, $prev_field, $field);
  $field['widget'] = $widget;

  // Make sure we know what module to invoke for field info.
  if (empty($field['module']) && !empty($field['type'])) {
    $field_types = _content_field_types();
    $field['module'] = $field_types[$field['type']]['module'];
  }

  // The storage type may need to be updated.
  $field['db_storage'] = content_storage_type($field);

  // Get a fresh copy of the column information whenever a field is created.
  $field['columns'] = (array) module_invoke($field['module'], 'field_settings', 'database columns', $field);
  if (empty($prev_field['widget']) || $prior_instances < 1) {

    // If this is the first instance, create the field.
    $field['db_storage'] = $field['multiple'] > 0 ? CONTENT_DB_STORAGE_PER_FIELD : CONTENT_DB_STORAGE_PER_CONTENT_TYPE;
    _content_field_write($field, 'create');
  }
  elseif (!empty($prev_field['widget']) && $prev_field['db_storage'] == CONTENT_DB_STORAGE_PER_CONTENT_TYPE && count($prior_instances) > 0) {

    // If the database storage has changed, update the field and previous instances.
    $field['db_storage'] = CONTENT_DB_STORAGE_PER_FIELD;
    foreach ($prior_instances as $instance) {
      $new_instance = $instance;
      $new_instance['db_storage'] = CONTENT_DB_STORAGE_PER_FIELD;

      // Invoke hook_content_fieldapi().
      module_invoke_all('content_fieldapi', 'update instance', $new_instance);
      content_alter_schema($instance, $new_instance);
    }
  }

  // Invoke hook_content_fieldapi().
  module_invoke_all('content_fieldapi', 'create instance', $field);

  // Update the field and the instance with the latest values.
  _content_field_write($field, 'update');
  _content_field_instance_write($field, 'create');
  content_alter_schema(array(), $field);
  if ($rebuild) {
    content_clear_type_cache(TRUE);
    menu_rebuild();
  }
  return $field;
}