Property info for fields

Last updated on
20 December 2016

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

Fields are added in automatically by the Entity API module, as long as the field type is supported. However, the module providing the field type has to provide the appropriate mapping to property info.

To support a new field type it sometimes suffices to specify the data type your field has to be mapped to - this is done with the 'property_type' key in hook_field_info(). With that information some default information is generated, which is already fine for most field-types that use only one db-column.

However, in some cases or if your field type makes use of multiple db-columns you need to alter the defaults by adding your own callback to the 'property_callbacks' key of hook_field_info(). For multiple-column fields it makes sense to specify the provided verbatim getters/and setters entity_metadata_field_verbatim_get and entity_metadata_field_verbatim_set, which just return or set the full data structure of your field in a certain language (e.g. array('value' => 'foo')). Then, use the property info key to describe this data structure and to specify any further getters or setters of nested properties.

For an example implementation look at entity_metadata_field_text_property_callback() and entity_field_info_alter(), which the entity api module provides for formatted text fields.

/**
 * Implements hook_field_info_alter().
 * Defines default property types for core field types.
 */
function entity_field_info_alter(&$field_info) {
  if (module_exists('text')) {
    $field_info['text']['property_type'] = 'text';
    $field_info['text']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
    $field_info['text_long']['property_type'] = 'text';
    $field_info['text_long']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
    $field_info['text_with_summary']['property_type'] = 'field_item_textsummary';
    $field_info['text_with_summary']['property_callbacks'][] = 'entity_metadata_field_text_property_callback';
  }
}

/**
 * Additional callback to adapt the property info for text fields. If a text
 * field is processed we make use of a separate data structure so that format
 * filters are available too. For the text value that is sanitized, this processed
 * value is returned by default.
 *
 * @see entity_metadata_field_entity_property_info()
 * @see entity_field_info_alter()
 * @see entity_property_text_formatted_info()
 */
function entity_metadata_field_text_property_callback(&$info, $entity_type, $field, $instance, $field_type) {
  if (!empty($instance['settings']['text_processing']) || $field['type'] == 'text_with_summary') {
    // Define a data structure for dealing with text that is formatted or has
    // a summary.
    $property = &$info[$entity_type]['bundles'][$instance['bundle']]['properties'][$field['field_name']];

    $property['getter callback'] = 'entity_metadata_field_verbatim_get';
    $property['setter callback'] = 'entity_metadata_field_verbatim_set';
    unset($property['query callback']);

    // For formatted text we use the type name 'text_formatted'.
    $property['type'] = ($field['cardinality'] != 1) ? 'list' : 'text_formatted';
    $property['property info'] = array(
      'value' => array(
        'type' => 'text',
        'label' => t('Text'),
        'sanitized' => TRUE,
        'getter callback' => 'entity_metadata_field_text_get',
        'setter callback' => 'entity_property_verbatim_set',
        'setter permission' => 'administer nodes',
        'raw getter callback' => 'entity_property_verbatim_get',
      ),
      'summary' => array(
        'type' => 'text',
        'label' => t('Summary'),
        'sanitized' => TRUE,
        'getter callback' => 'entity_metadata_field_text_get',
        'setter callback' => 'entity_property_verbatim_set',
        'setter permission' => 'administer nodes',
        'raw getter callback' => 'entity_property_verbatim_get',
      ),
      'format' => array(
        'type' => 'token',
        'label' => t('Text format'),
        'options list' => 'entity_metadata_field_text_formats',
        'getter callback' => 'entity_property_verbatim_get',
      ),
    );
    
    // Enable auto-creation of the item, so that it is possible to just set
    // the textual or summary value.
    $property['auto creation'] = 'entity_property_create_array';

    if ($field['type'] != 'text_with_summary') {
      unset($property['property info']['summary']);
    }
  }
}

Also, make sure to read the docs provided at entity_hook_field_info().

More

Useful information on making a custom field accessible through Entity API can be found at: http://drupal.org/node/1681610

Help improve this page

Page status: No known problems

You can: