entity.views.inc in Entity API 7

Provide views data for modules making use of the entity CRUD API.

File

views/entity.views.inc

<?php

/**
 * @file
 * Provide views data for modules making use of the entity CRUD API.
 */

/**
 * Implements hook_views_data().
 *
 * Provides Views integration for entities if they satisfy one of these
 * conditions:
 *  - hook_entity_info() specifies a 'views controller class' key.
 *  - hook_entity_info() specifies a 'module' key, and the module does not
 *    implement hook_views_data().
 *
 * @see entity_crud_hook_entity_info()
 * @see entity_views_table_definition()
 */
function entity_views_data() {
  $data = array();
  foreach (entity_crud_get_info() as $type => $info) {

    // Provide default integration with the basic controller class if we know
    // the module providing the entity and it does not provide views integration.
    if (!isset($info['views controller class'])) {
      $info['views controller class'] = isset($info['module']) && !module_hook($info['module'], 'views_data') ? 'EntityDefaultViewsController' : FALSE;
    }
    if ($info['views controller class']) {
      $controller = new $info['views controller class']($type);

      // Relationship data may return views data for already existing tables,
      // so merge results on the second level.
      foreach ($controller
        ->views_data() as $table => $table_data) {
        $data += array(
          $table => array(),
        );
        $data[$table] = array_merge($data[$table], $table_data);
      }
    }
  }

  // Add tables based upon data selection "queries" for all entity types.
  foreach (entity_get_info() as $type => $info) {
    $table = entity_views_table_definition($type);
    if ($table) {
      $data['entity_' . $type] = $table;
    }

    // Generally expose properties marked as 'entity views field'.
    $data['views_entity_' . $type] = array();
    foreach (entity_get_all_property_info($type) as $key => $property) {
      if (!empty($property['entity views field'])) {
        entity_views_field_definition($key, $property, $data['views_entity_' . $type]);
      }
    }
  }

  // Expose generally usable entity-related fields.
  foreach (entity_get_info() as $entity_type => $info) {
    if (entity_type_supports($entity_type, 'view')) {

      // Expose a field allowing to display the rendered entity.
      $data['views_entity_' . $entity_type]['rendered_entity'] = array(
        'title' => t('Rendered @entity-type', array(
          '@entity-type' => $info['label'],
        )),
        'help' => t('The @entity-type of the current relationship rendered using a view mode.', array(
          '@entity-type' => $info['label'],
        )),
        'field' => array(
          'handler' => 'entity_views_handler_field_entity',
          'type' => $entity_type,
          // The EntityFieldHandlerHelper treats the 'entity object' data
          // selector as special case for loading the base entity.
          'real field' => 'entity object',
        ),
      );
    }
  }
  $data['entity__global']['table']['group'] = t('Entity');
  $data['entity__global']['table']['join'] = array(
    // #global let's it appear all the time.
    '#global' => array(),
  );
  $data['entity__global']['entity'] = array(
    'title' => t('Rendered entity'),
    'help' => t('Displays a single chosen entity.'),
    'area' => array(
      'handler' => 'entity_views_handler_area_entity',
    ),
  );
  return $data;
}

/**
 * Helper function for getting data selection based entity Views table definitions.
 *
 * This creates extra tables for each entity type that are not associated with a
 * query plugin (and thus are not base tables) and just rely on the entities to
 * retrieve the displayed data. To obtain the entities corresponding to a
 * certain result set, the field handlers defined on the table use a generic
 * interface defined for query plugins that are based on entity handling, and
 * which is described in the entity_views_example_query class.
 *
 * These tables are called "data selection tables".
 *
 * Other modules providing Views integration with new query plugins that are
 * based on entities can then use these tables as a base for their own tables
 * (by directly using this method and modifying the returned table) and/or by
 * specifying relationships to them. The tables returned here already specify
 * relationships to each other wherever an entity contains a reference to
 * another (e.g., the node author constructs a relationship from nodes to
 * users).
 *
 * As filtering and other query manipulation is potentially more plugin-specific
 * than the display, only field handlers and relationships are provided with
 * these tables. By providing a add_selector_orderby() method, the query plugin
 * can, however, support click-sorting for the field handlers in these tables.
 *
 * For a detailed discussion see http://drupal.org/node/1266036
 *
 * For example use see the Search API views module in the Search API project:
 * http://drupal.org/project/search_api
 *
 * @param $type
 *   The entity type whose table definition should be returned.
 * @param $exclude
 *   Whether properties already exposed as 'entity views field' should be
 *   excluded. Defaults to TRUE, as they are available for all views tables for
 *   the entity type anyways.
 *
 * @return array
 *   An array containing the data selection Views table definition for the
 *   entity type.
 *
 * @see entity_views_field_definition()
 */
function entity_views_table_definition($type, $exclude = TRUE) {

  // As other modules might want to copy these tables as a base for their own
  // Views integration, we statically cache the tables to save some time.
  $tables =& drupal_static(__FUNCTION__, array());
  if (!isset($tables[$type])) {

    // Work-a-round to fix updating, see http://drupal.org/node/1330874.
    // Views data might be rebuilt on update.php before the registry is rebuilt,
    // thus the class cannot be auto-loaded.
    if (!class_exists('EntityFieldHandlerHelper')) {
      module_load_include('inc', 'entity', 'views/handlers/entity_views_field_handler_helper');
    }
    $info = entity_get_info($type);
    $tables[$type]['table'] = array(
      'group' => $info['label'],
      'entity type' => $type,
    );
    foreach (entity_get_all_property_info($type) as $key => $property) {
      if (!$exclude || empty($property['entity views field'])) {
        entity_views_field_definition($key, $property, $tables[$type]);
      }
    }
  }
  return $tables[$type];
}

/**
 * Helper function for adding a Views field definition to data selection based Views tables.
 *
 * @param $field
 *   The data selector of the field to add. E.g. "title" would derive the node
 *   title property, "body:summary" the node body's summary.
 * @param array $property_info
 *   The property information for which to create a field definition.
 * @param array $table
 *   The table into which the definition should be inserted.
 * @param $title_prefix
 *   Internal use only.
 *
 * @see entity_views_table_definition()
 */
function entity_views_field_definition($field, array $property_info, array &$table, $title_prefix = '') {
  $additional = array();
  $additional_field = array();

  // Create a valid Views field identifier (no colons, etc.). Keep the original
  // data selector as real field though.
  $key = _entity_views_field_identifier($field, $table);
  if ($key != $field) {
    $additional['real field'] = $field;
  }
  $field_name = EntityFieldHandlerHelper::get_selector_field_name($field);
  $field_handlers = entity_views_get_field_handlers();
  $property_info += entity_property_info_defaults();
  $type = entity_property_extract_innermost_type($property_info['type']);
  $title = $title_prefix . $property_info['label'];
  if ($info = entity_get_info($type)) {
    $additional['relationship'] = array(
      'handler' => $field_handlers['relationship'],
      'base' => 'entity_' . $type,
      'base field' => $info['entity keys']['id'],
      'relationship field' => $field,
      'label' => $title,
    );
    if ($property_info['type'] != $type) {

      // This is a list of entities, so we should mark the relationship as such.
      $additional['relationship']['multiple'] = TRUE;
    }

    // Implementers of the field handlers alter hook could add handlers for
    // specific entity types.
    if (!isset($field_handlers[$type])) {
      $type = 'entity';
    }
  }
  elseif (!empty($property_info['field'])) {
    $type = 'field';

    // Views' Field API field handler needs some extra definitions to work.
    $additional_field['field_name'] = $field_name;
    $additional_field['entity_tables'] = array();
    $additional_field['entity type'] = $table['table']['entity type'];
    $additional_field['is revision'] = FALSE;
  }
  elseif (isset($property_info['options list']) && is_callable($property_info['options list'])) {

    // If this is a nested property, we need to get rid of all prefixes first.
    $type = 'options';
    $additional_field['options callback'] = array(
      'function' => $property_info['options list'],
      'info' => $property_info,
    );
  }
  elseif ($type == 'decimal') {
    $additional_field['float'] = TRUE;
  }
  if (isset($field_handlers[$type])) {
    $table += array(
      $key => array(),
    );
    $table[$key] += array(
      'title' => $title,
      'help' => empty($property_info['description']) ? t('(No information available)') : $property_info['description'],
      'field' => array(),
    );
    $table[$key]['field'] += array(
      'handler' => $field_handlers[$type],
      'type' => $property_info['type'],
    );
    $table[$key] += $additional;
    $table[$key]['field'] += $additional_field;
  }
  if (!empty($property_info['property info'])) {
    foreach ($property_info['property info'] as $nested_key => $nested_property) {
      entity_views_field_definition($field . ':' . $nested_key, $nested_property, $table, $title . ' » ');
    }
  }
}

/**
 * @return array
 *   The handlers to use for the data selection based Views tables.
 *
 * @see hook_entity_views_field_handlers_alter()
 */
function entity_views_get_field_handlers() {
  $field_handlers = drupal_static(__FUNCTION__);
  if (!isset($field_handlers)) {

    // Field handlers for the entity tables, by type.
    $field_handlers = array(
      'text' => 'entity_views_handler_field_text',
      'token' => 'entity_views_handler_field_text',
      'integer' => 'entity_views_handler_field_numeric',
      'decimal' => 'entity_views_handler_field_numeric',
      'date' => 'entity_views_handler_field_date',
      'duration' => 'entity_views_handler_field_duration',
      'boolean' => 'entity_views_handler_field_boolean',
      'uri' => 'entity_views_handler_field_uri',
      'options' => 'entity_views_handler_field_options',
      'field' => 'entity_views_handler_field_field',
      'entity' => 'entity_views_handler_field_entity',
      'relationship' => 'entity_views_handler_relationship',
    );
    drupal_alter('entity_views_field_handlers', $field_handlers);
  }
  return $field_handlers;
}

/**
 * Helper function for creating valid Views field identifiers out of data selectors.
 *
 * Uses $table to test whether the identifier is already used, and also
 * recognizes if a definition for the same field is already present and returns
 * that definition's identifier.
 *
 * @return string
 *   A valid Views field identifier that is not yet used as a key in $table.
 */
function _entity_views_field_identifier($field, array $table) {
  $key = $base = preg_replace('/[^a-zA-Z0-9]+/S', '_', $field);
  $i = 0;

  // The condition checks whether this sanitized field identifier is already
  // used for another field in this table (and whether the identifier is
  // "table", which can never be used).
  // If $table[$key] is set, the identifier is already used, but this might be
  // already for the same field. To test that, we need the original field name,
  // which is either $table[$key]['real field'], if set, or $key. If this
  // original field name is equal to $field, we can use that key. Otherwise, we
  // append numeric suffixes until we reach an unused key.
  while ($key == 'table' || isset($table[$key]) && (isset($table[$key]['real field']) ? $table[$key]['real field'] : $key) != $field) {
    $key = $base . '_' . ++$i;
  }
  return $key;
}

/**
 * Implements hook_views_plugins().
 */
function entity_views_plugins() {

  // Have views cache the table list for us so it gets
  // cleared at the appropriate times.
  $data = views_cache_get('entity_base_tables', TRUE);
  if (!empty($data->data)) {
    $base_tables = $data->data;
  }
  else {
    $base_tables = array();
    foreach (views_fetch_data() as $table => $data) {
      if (!empty($data['table']['entity type']) && !empty($data['table']['base'])) {
        $base_tables[] = $table;
      }
    }
    views_cache_set('entity_base_tables', $base_tables, TRUE);
  }
  if (!empty($base_tables)) {
    return array(
      'module' => 'entity',
      'row' => array(
        'entity' => array(
          'title' => t('Rendered entity'),
          'help' => t('Renders a single entity in a specific view mode (e.g. teaser).'),
          'handler' => 'entity_views_plugin_row_entity_view',
          'uses fields' => FALSE,
          'uses options' => TRUE,
          'type' => 'normal',
          'base' => $base_tables,
        ),
      ),
    );
  }
}

/**
 * Default controller for generating basic views integration.
 *
 * The controller tries to generate suiting views integration for the entity
 * based upon the schema information of its base table and the provided entity
 * property information.
 * For that it is possible to map a property name to its schema/views field
 * name by adding a 'schema field' key with the name of the field as value to
 * the property info.
 */
class EntityDefaultViewsController {
  protected $type, $info, $relationships;
  public function __construct($type) {
    $this->type = $type;
    $this->info = entity_get_info($type);
  }

  /**
   * Defines the result for hook_views_data().
   */
  public function views_data() {
    $data = array();
    $this->relationships = array();
    if (!empty($this->info['base table'])) {
      $table = $this->info['base table'];

      // Define the base group of this table. Fields that don't
      // have a group defined will go into this field by default.
      $data[$table]['table']['group'] = drupal_ucfirst($this->info['label']);
      $data[$table]['table']['entity type'] = $this->type;

      // If the plural label isn't available, use the regular label.
      $label = isset($this->info['plural label']) ? $this->info['plural label'] : $this->info['label'];
      $data[$table]['table']['base'] = array(
        'field' => $this->info['entity keys']['id'],
        'access query tag' => $this->type . '_access',
        'title' => drupal_ucfirst($label),
        'help' => isset($this->info['description']) ? $this->info['description'] : '',
      );
      $data[$table]['table']['entity type'] = $this->type;
      $data[$table] += $this
        ->schema_fields();

      // Add in any reverse-relationships which have been determined.
      $data += $this->relationships;
    }
    if (!empty($this->info['revision table']) && !empty($this->info['entity keys']['revision'])) {
      $revision_table = $this->info['revision table'];
      $data[$table]['table']['default_relationship'] = array(
        $revision_table => array(
          'table' => $revision_table,
          'field' => $this->info['entity keys']['revision'],
        ),
      );

      // Define the base group of this table. Fields that don't
      // have a group defined will go into this field by default.
      $data[$revision_table]['table']['group'] = drupal_ucfirst($this->info['label']) . ' ' . t('Revisions');
      $data[$revision_table]['table']['entity type'] = $this->type;

      // If the plural label isn't available, use the regular label.
      $label = isset($this->info['plural label']) ? $this->info['plural label'] : $this->info['label'];
      $data[$revision_table]['table']['base'] = array(
        'field' => $this->info['entity keys']['revision'],
        'access query tag' => $this->type . '_access',
        'title' => drupal_ucfirst($label) . ' ' . t('Revisions'),
        'help' => (isset($this->info['description']) ? $this->info['description'] . ' ' : '') . t('Revisions'),
      );
      $data[$revision_table]['table']['entity type'] = $this->type;
      $data[$revision_table] += $this
        ->schema_revision_fields();

      // Add in any reverse-relationships which have been determined.
      $data += $this->relationships;

      // For other base tables, explain how we join.
      $data[$revision_table]['table']['join'] = array(
        // Directly links to base table.
        $table => array(
          'left_field' => $this->info['entity keys']['revision'],
          'field' => $this->info['entity keys']['revision'],
        ),
      );
      $data[$revision_table]['table']['default_relationship'] = array(
        $table => array(
          'table' => $table,
          'field' => $this->info['entity keys']['id'],
        ),
      );
    }
    return $data;
  }

  /**
   * Try to come up with some views fields with the help of the schema and
   * the entity property information.
   */
  protected function schema_fields() {
    $schema = drupal_get_schema($this->info['base table']);
    $properties = entity_get_property_info($this->type) + array(
      'properties' => array(),
    );
    $data = array();
    foreach ($properties['properties'] as $name => $property_info) {
      if (isset($property_info['schema field']) && isset($schema['fields'][$property_info['schema field']])) {
        if ($views_info = $this
          ->map_from_schema_info($name, $schema['fields'][$property_info['schema field']], $property_info)) {
          $data[$name] = $views_info;
        }
      }
    }
    return $data;
  }

  /**
   * Try to come up with some views fields with the help of the revision schema
   * and the entity property information.
   */
  protected function schema_revision_fields() {
    $data = array();
    if (!empty($this->info['revision table'])) {
      $schema = drupal_get_schema($this->info['revision table']);
      $properties = entity_get_property_info($this->type) + array(
        'properties' => array(),
      );
      foreach ($properties['properties'] as $name => $property_info) {
        if (isset($property_info['schema field']) && isset($schema['fields'][$property_info['schema field']])) {
          if ($views_info = $this
            ->map_from_schema_info($name, $schema['fields'][$property_info['schema field']], $property_info)) {
            $data[$name] = $views_info;
          }
        }
      }
    }
    return $data;
  }

  /**
   * Comes up with views information based on the given schema and property
   * info.
   */
  protected function map_from_schema_info($property_name, $schema_field_info, $property_info) {
    $type = isset($property_info['type']) ? $property_info['type'] : 'text';
    $views_field_name = $property_info['schema field'];
    $return = array();
    if (!empty($schema_field_info['serialize'])) {
      return FALSE;
    }
    $description = array(
      'title' => $property_info['label'],
      'help' => isset($property_info['description']) ? $property_info['description'] : NULL,
    );

    // Add in relationships to related entities.
    if (($info = entity_get_info($type)) && !empty($info['base table'])) {

      // Prepare reversed relationship data.
      $label_lowercase = drupal_strtolower($this->info['label'][0]) . drupal_substr($this->info['label'], 1);
      $property_label_lowercase = drupal_strtolower($property_info['label'][0]) . drupal_substr($property_info['label'], 1);

      // We name the field of the first reverse-relationship just with the
      // base table to be backward compatible, for subsequents relationships we
      // append the views field name in order to get a unique name.
      $name = !isset($this->relationships[$info['base table']][$this->info['base table']]) ? $this->info['base table'] : $this->info['base table'] . '_' . $views_field_name;
      $this->relationships[$info['base table']][$name] = array(
        'title' => $this->info['label'],
        'help' => t("Associated @label via the @label's @property.", array(
          '@label' => $label_lowercase,
          '@property' => $property_label_lowercase,
        )),
        'relationship' => array(
          'label' => $this->info['label'],
          'handler' => $this
            ->getRelationshipHandlerClass($this->type, $type),
          'base' => $this->info['base table'],
          'base field' => $views_field_name,
          'relationship field' => isset($info['entity keys']['name']) ? $info['entity keys']['name'] : $info['entity keys']['id'],
        ),
      );
      $return['relationship'] = array(
        'label' => drupal_ucfirst($info['label']),
        'handler' => $this
          ->getRelationshipHandlerClass($type, $this->type),
        'base' => $info['base table'],
        'base field' => isset($info['entity keys']['name']) ? $info['entity keys']['name'] : $info['entity keys']['id'],
        'relationship field' => $views_field_name,
      );

      // Add in direct field/filters/sorts for the id itself too.
      $type = isset($info['entity keys']['name']) ? 'token' : 'integer';

      // Append the views-field-name to the title if it is different to the
      // property name.
      if ($property_name != $views_field_name) {
        $description['title'] .= ' ' . $views_field_name;
      }
    }
    switch ($type) {
      case 'token':
      case 'text':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_field',
            'click sortable' => TRUE,
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_string',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_string',
          ),
        );
        break;
      case 'decimal':
      case 'integer':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_field_numeric',
            'click sortable' => TRUE,
            'float' => $type == 'decimal',
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_numeric',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_numeric',
          ),
        );
        break;
      case 'date':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_field_date',
            'click sortable' => TRUE,
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort_date',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_date',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_date',
          ),
        );
        break;
      case 'duration':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'entity_views_handler_field_duration',
            'click sortable' => TRUE,
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_numeric',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_numeric',
          ),
        );
        break;
      case 'uri':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_field_url',
            'click sortable' => TRUE,
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_string',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_string',
          ),
        );
        break;
      case 'boolean':
        $return += $description + array(
          'field' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_field_boolean',
            'click sortable' => TRUE,
          ),
          'sort' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_sort',
          ),
          'filter' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_filter_boolean_operator',
          ),
          'argument' => array(
            'real field' => $views_field_name,
            'handler' => 'views_handler_argument_string',
          ),
        );
        break;
    }

    // If there is an options list callback, add to the filter and field.
    if (isset($return['filter']) && !empty($property_info['options list'])) {
      $return['filter']['handler'] = 'views_handler_filter_in_operator';
      $return['filter']['options callback'] = array(
        'EntityDefaultViewsController',
        'optionsListCallback',
      );
      $return['filter']['options arguments'] = array(
        $this->type,
        $property_name,
        'view',
      );
    }

    // @todo This class_exists is needed until views 3.2.
    if (isset($return['field']) && !empty($property_info['options list']) && class_exists('views_handler_field_machine_name')) {
      $return['field']['handler'] = 'views_handler_field_machine_name';
      $return['field']['options callback'] = array(
        'EntityDefaultViewsController',
        'optionsListCallback',
      );
      $return['field']['options arguments'] = array(
        $this->type,
        $property_name,
        'view',
      );
    }
    return $return;
  }

  /**
   * Determines the handler to use for a relationship to an entity type.
   *
   * @param $entity_type
   *   The entity type to join to.
   * @param $left_type
   *   The data type from which to join.
   */
  public function getRelationshipHandlerClass($entity_type, $left_type) {

    // Look for an entity type which is used as bundle for the given entity
    // type. If there is one, allow filtering the relation by bundle by using
    // our own handler.
    foreach (entity_get_info() as $type => $info) {

      // In case we already join from the bundle entity we do not need to filter
      // by bundle entity any more, so we stay with the general handler.
      if (!empty($info['bundle of']) && $info['bundle of'] == $entity_type && $type != $left_type) {
        return 'entity_views_handler_relationship_by_bundle';
      }
    }
    return 'views_handler_relationship';
  }

  /**
   * A callback returning property options, suitable to be used as views options callback.
   */
  public static function optionsListCallback($type, $selector, $op = 'view') {
    $wrapper = entity_metadata_wrapper($type, NULL);
    $parts = explode(':', $selector);
    foreach ($parts as $part) {
      $wrapper = $wrapper
        ->get($part);
    }
    return $wrapper
      ->optionsList($op);
  }

}

Functions

Name	Description
entity_views_data	Implements hook_views_data().
entity_views_field_definition	Helper function for adding a Views field definition to data selection based Views tables.
entity_views_get_field_handlers
entity_views_plugins	Implements hook_views_plugins().
entity_views_table_definition	Helper function for getting data selection based entity Views table definitions.
_entity_views_field_identifier	Helper function for creating valid Views field identifiers out of data selectors.

Classes

Name	Description
EntityDefaultViewsController	Default controller for generating basic views integration.