<?php

/**

 * @file

 * Hooks provided by the Field module.

 */

/**

 * @addtogroup hooks

 * @{

 */

/**

 * Exposes "pseudo-field" components on fieldable entities.

 *

 * Field UI's "Manage fields" and "Manage display" pages let users re-order

 * fields, but also non-field components. For nodes, these include the title,

 * poll choices, and other elements exposed by modules through hook_form() or

 * hook_form_alter().

 *

 * Fieldable entities or modules that want to have their components supported

 * should expose them using this hook. The user-defined settings (weight,

 * visible) are automatically applied on rendered forms and displayed

 * entities in a #pre_render callback added by field_attach_form() and

 * field_attach_view().

 *

 * @see _field_extra_fields_pre_render()

 * @see hook_field_extra_fields_alter()

 *

 * @return

 *   A nested array of 'pseudo-field' elements. Each list is nested within the

 *   following keys: entity type, bundle name, context (either 'form' or

 *   'display'). The keys are the name of the elements as appearing in the

 *   renderable array (either the entity form or the displayed entity). The

 *   value is an associative array:

 *   - label: The human readable name of the element.

 *   - description: A short description of the element contents.

 *   - weight: The default weight of the element.

 *   - edit: (optional) String containing markup (normally a link) used as the

 *     element's 'edit' operation in the administration interface. Only for

 *     'form' context.

 *   - delete: (optional) String containing markup (normally a link) used as the

 *     element's 'delete' operation in the administration interface. Only for

 *     'form' context.

 *

 * @ingroup field_types

 */

function hook_field_extra_fields() {

  $extra['node']['poll'] = array(

    'form' => array(

      'choice_wrapper' => array(

        'label' => t('Poll choices'),

        'description' => t('Poll choices'),

        'weight' => -4,

      ),

      'settings' => array(

        'label' => t('Poll settings'),

        'description' => t('Poll module settings'),

        'weight' => -3,

      ),

    ),

    'display' => array(

      'poll_view_voting' => array(

        'label' => t('Poll vote'),

        'description' => t('Poll vote'),

        'weight' => 0,

      ),

      'poll_view_results' => array(

        'label' => t('Poll results'),

        'description' => t('Poll results'),

        'weight' => 0,

      ),

    )

  );

  return $extra;

}

/**

 * Alter "pseudo-field" components on fieldable entities.

 *

 * @param $info

 *   The associative array of 'pseudo-field' components.

 *

 * @see hook_field_extra_fields()

 *

 * @ingroup field_types

 */

function hook_field_extra_fields_alter(&$info) {

  // Force node title to always be at the top of the list by default.

  foreach (node_type_get_types() as $bundle) {

    if (isset($info['node'][$bundle->type]['form']['title'])) {

      $info['node'][$bundle->type]['form']['title']['weight'] = -20;

    }

  }

}

/**

 * @defgroup field_types Field Types API

 * @{

 * Define field types.

 *

 * In the Field API, each field has a type, which determines what kind of data

 * (integer, string, date, etc.) the field can hold, which settings it provides,

 * and so on. The data type(s) accepted by a field are defined in

 * hook_field_schema(); other basic properties of a field are defined in

 * hook_field_info(). The other hooks below are called by the Field Attach API

 * to perform field-type-specific actions.

 *

 * The Field Types API also defines two kinds of pluggable handlers: widgets

 * and formatters. @link field_widget Widgets @endlink specify how the field

 * appears in edit forms, while @link field_formatter formatters @endlink

 * specify how the field appears in displayed entities.

 *

 * A third kind of pluggable handlers, storage backends, is defined by the

 * @link field_storage Field Storage API @endlink.

 *

 * See @link field Field API @endlink for information about the other parts of

 * the Field API.

 */

/**

 * Define Field API field types.

 *

 * Along with this hook, you also need to implement other hooks. See

 * @link field_types Field Types API @endlink for more information.

 *

 * @return

 *   An array whose keys are field type names and whose values are arrays

 *   describing the field type, with the following key/value pairs:

 *   - label: The human-readable name of the field type.

 *   - description: A short description for the field type.

 *   - settings: An array whose keys are the names of the settings available

 *     for the field type, and whose values are the default values for those

 *     settings.

 *   - instance_settings: An array whose keys are the names of the settings

 *     available for instances of the field type, and whose values are the

 *     default values for those settings. Instance-level settings can have

 *     different values on each field instance, and thus allow greater

 *     flexibility than field-level settings. It is recommended to put settings

 *     at the instance level whenever possible. Notable exceptions: settings

 *     acting on the schema definition, or settings that Views needs to use

 *     across field instances (for example, the list of allowed values).

 *   - default_widget: The machine name of the default widget to be used by

 *     instances of this field type, when no widget is specified in the

 *     instance definition. This widget must be available whenever the field

 *     type is available (i.e. provided by the field type module, or by a module

 *     the field type module depends on).

 *   - default_formatter: The machine name of the default formatter to be used

 *     by instances of this field type, when no formatter is specified in the

 *     instance definition. This formatter must be available whenever the field

 *     type is available (i.e. provided by the field type module, or by a module

 *     the field type module depends on).

 *   - no_ui: (optional) A boolean specifying that users should not be allowed

 *     to create fields and instances of this field type through the UI. Such

 *     fields can only be created programmatically with field_create_field()

 *     and field_create_instance(). Defaults to FALSE.

 *

 * @see hook_field_info_alter()

 */

function hook_field_info() {

  return array(

    'text' => array(

      'label' => t('Text'),

      'description' => t('This field stores varchar text in the database.'),

      'settings' => array('max_length' => 255),

      'instance_settings' => array('text_processing' => 0),

      'default_widget' => 'text_textfield',

      'default_formatter' => 'text_default',

    ),

    'text_long' => array(

      'label' => t('Long text'),

      'description' => t('This field stores long text in the database.'),

      'settings' => array('max_length' => ''),

      'instance_settings' => array('text_processing' => 0),

      'default_widget' => 'text_textarea',

      'default_formatter' => 'text_default',

    ),

    'text_with_summary' => array(

      'label' => t('Long text and summary'),

      'description' => t('This field stores long text in the database along with optional summary text.'),

      'settings' => array('max_length' => ''),

      'instance_settings' => array('text_processing' => 1, 'display_summary' => 0),

      'default_widget' => 'text_textarea_with_summary',

      'default_formatter' => 'text_summary_or_trimmed',

    ),

  );

}

/**

 * Perform alterations on Field API field types.

 *

 * @param $info

 *   Array of information on field types exposed by hook_field_info()

 *   implementations.

 */

function hook_field_info_alter(&$info) {

  // Add a setting to all field types.

  foreach ($info as $field_type => $field_type_info) {

    $info[$field_type]['settings'] += array(

      'mymodule_additional_setting' => 'default value',

    );

  }

  // Change the default widget for fields of type 'foo'.

  if (isset($info['foo'])) {

    $info['foo']['default widget'] = 'mymodule_widget';

  }

}

/**

 * Define the Field API schema for a field structure.

 *

 * This is invoked when a field is created, in order to obtain the database

 * schema from the module that defines the field's type.

 *

 * This hook must be defined in the module's .install file for it to be detected

 * during installation and upgrade.

 *

 * @param $field

 *   A field structure.

 *

 * @return

 *   An associative array with the following keys:

 *   - columns: An array of Schema API column specifications, keyed by column

 *     name. This specifies what comprises a value for a given field. For

 *     example, a value for a number field is simply 'value', while a value for

 *     a formatted text field is the combination of 'value' and 'format'. It is

 *     recommended to avoid having the column definitions depend on field

 *     settings when possible. No assumptions should be made on how storage

 *     engines internally use the original column name to structure their

 *     storage.

 *   - indexes: (optional) An array of Schema API indexes definitions. Only

 *     columns that appear in the 'columns' array are allowed. Those indexes

 *     will be used as default indexes. Callers of field_create_field() can

 *     specify additional indexes, or, at their own risk, modify the default

 *     indexes specified by the field-type module. Some storage engines might

 *     not support indexes.

 *   - foreign keys: (optional) An array of Schema API foreign keys

 *     definitions.

 */

function hook_field_schema($field) {

  if ($field['type'] == 'text_long') {

    $columns = array(

      'value' => array(

        'type' => 'text',

        'size' => 'big',

        'not null' => FALSE,

      ),

    );

  }

  else {

    $columns = array(

      'value' => array(

        'type' => 'varchar',

        'length' => $field['settings']['max_length'],

        'not null' => FALSE,

      ),

    );

  }

  $columns += array(

    'format' => array(

      'type' => 'varchar',

      'length' => 255,

      'not null' => FALSE,

    ),

  );

  return array(

    'columns' => $columns,

    'indexes' => array(

      'format' => array('format'),

    ),

    'foreign keys' => array(

      'format' => array(

        'table' => 'filter_format',

        'columns' => array('format' => 'format'),

      ),

    ),

  );

}

/**

 * Define custom load behavior for this module's field types.

 *

 * Unlike most other field hooks, this hook operates on multiple entities. The

 * $entities, $instances and $items parameters are arrays keyed by entity ID.

 * For performance reasons, information for all available entity should be

 * loaded in a single query where possible.

 *

 * Note that the changes made to the field values get cached by the field cache

 * for subsequent loads. You should never use this hook to load fieldable

 * entities, since this is likely to cause infinite recursions when

 * hook_field_load() is run on those as well. Use

 * hook_field_formatter_prepare_view() instead.

 *

 * Make changes or additions to field values by altering the $items parameter by

 * reference. There is no return value.

 *

 * @param $entity_type

 *   The type of $entity.

 * @param $entities

 *   Array of entities being loaded, keyed by entity ID.

 * @param $field

 *   The field structure for the operation.

 * @param $instances

 *   Array of instance structures for $field for each entity, keyed by entity

 *   ID.

 * @param $langcode

 *   The language code associated with $items.

 * @param $items

 *   Array of field values already loaded for the entities, keyed by entity ID.

 *   Store your changes in this parameter (passed by reference).

 * @param $age

 *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or

 *   FIELD_LOAD_REVISION to load the version indicated by each entity.

 */

function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) {

  // Sample code from text.module: precompute sanitized strings so they are

  // stored in the field cache.

  foreach ($entities as $id => $entity) {

    foreach ($items[$id] as $delta => $item) {

      // Only process items with a cacheable format, the rest will be handled

      // by formatters if needed.

      if (empty($instances[$id]['settings']['text_processing']) || filter_format_allowcache($item['format'])) {

        $items[$id][$delta]['safe_value'] = isset($item['value']) ? _text_sanitize($instances[$id], $langcode, $item, 'value') : '';

        if ($field['type'] == 'text_with_summary') {

          $items[$id][$delta]['safe_summary'] = isset($item['summary']) ? _text_sanitize($instances[$id], $langcode, $item, 'summary') : '';

        }

      }

    }

  }

}

/**

 * Prepare field values prior to display.

 *

 * This hook is invoked before the field values are handed to formatters

 * for display, and runs before the formatters' own

 * hook_field_formatter_prepare_view().

 *

 * Unlike most other field hooks, this hook operates on multiple entities. The

 * $entities, $instances and $items parameters are arrays keyed by entity ID.

 * For performance reasons, information for all available entities should be

 * loaded in a single query where possible.

 *

 * Make changes or additions to field values by altering the $items parameter by

 * reference. There is no return value.

 *

 * @param $entity_type

 *   The type of $entity.

 * @param $entities

 *   Array of entities being displayed, keyed by entity ID.

 * @param $field

 *   The field structure for the operation.

 * @param $instances

 *   Array of instance structures for $field for each entity, keyed by entity

 *   ID.

 * @param $langcode

 *   The language associated to $items.

 * @param $items

 *   $entity->{$field['field_name']}, or an empty array if unset.

 */

function hook_field_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items) {

  // Sample code from image.module: if there are no images specified at all,

  // use the default image.

  foreach ($entities as $id => $entity) {

    if (empty($items[$id]) && $field['settings']['default_image']) {

      if ($file = file_load($field['settings']['default_image'])) {

        $items[$id][0] = (array) $file + array(

          'is_default' => TRUE,

          'alt' => '',

          'title' => '',

        );

      }

    }

  }

}

/**

 * Validate this module's field data.

 *

 * If there are validation problems, add to the $errors array (passed by

 * reference). There is no return value.

 *

 * @param $entity_type

 *   The type of $entity.

 * @param $entity

 *   The entity for the operation.

 * @param $field

 *   The field structure for the operation.

 * @param $instance

 *   The instance structure for $field on $entity's bundle.

 * @param $langcode

 *   The language associated with $items.

 * @param $items

 *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.

 * @param $errors

 *   The array of errors (keyed by field name, language code, and delta) that

 *   have already been reported for the entity. The function should add its

 *   errors to this array. Each error is an associative array with the following

 *   keys and values:

 *   - error: An error code (should be a string prefixed with the module name).

 *   - message: The human readable message to be displayed.

 */

function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {

  foreach ($items as $delta => $item) {

    if (!empty($item['value'])) {

      if (!empty($field['settings']['max_length']) && drupal_strlen($item['value']) > $field['settings']['max_length']) {

        $errors[$field['field_name']][$langcode][$delta][] = array(

          'error' => 'text_max_length',

          'message' => t('%name: the value may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length'])),

        );

      }

    }

  }

}

/**

 * Define custom presave behavior for this module's field types.

 *

 * Make changes or additions to field values by altering the $items parameter by

 * reference. There is no return value.

 *

 * @param $entity_type

 *   The type of $entity.

 * @param $entity

 *   The entity for the operation.

 * @param $field

 *   The field structure for the operation.

 * @param $instance

 *   The instance structure for $field on $entity's bundle.

 * @param $langcode

 *   The language associated with $items.

 * @param $items

 *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.

 */

function hook_field_presave($entity_type, $entity, $field, $instance, $langcode, &$items) {

  if ($field['type'] == 'number_decimal') {

    // Let PHP round the value to ensure consistent behavior across storage

    // backends.

    foreach ($items as $delta => $item) {

      if (isset($item['value'])) {

        $items[$delta]['value'] = round($item['value'], $field['settings']['scale']);

      }

    }

  }

}

/**

 * Define custom insert behavior for this module's field data.

 *

 * This hook is invoked from field_attach_insert() on the module that defines a