function hook_views_data

Describes data tables (or the equivalent) to Views.

This hook should be placed in MODULENAME.views.inc and it will be auto loaded. MODULENAME.views.inc must be in the directory specified by the 'path' key returned by MODULENAME_views_api(), or the same directory as the .module file, if 'path' is unspecified.

Return value

array An associative array describing the data structure. Primary key is the name used internally by Views for the table(s) – usually the actual table name. The values for the key entries are described in detail below.

Related topics

File

./views.api.php, line 307

Code

function hook_views_data() {
    // This example describes how to write hook_views_data() for the following
    // table:
    //
    // CREATE TABLE example_table (
    //   nid INT(11) NOT NULL COMMENT 'Primary key; refers to {node}.nid.',
    //   plain_text_field VARCHAR(32) COMMENT 'Just a plain text field.',
    //   numeric_field INT(11) COMMENT 'Just a numeric field.',
    //   boolean_field INT(1) COMMENT 'Just an on/off field.',
    //   timestamp_field INT(8) COMMENT 'Just a timestamp field.',
    //   PRIMARY KEY(nid)
    // );
    // First, the entry $data['example_table']['table'] describes properties of
    // the actual table – not its content.
    // The 'group' index will be used as a prefix in the UI for any of this
    // table's fields, sort criteria, etc. so it's easy to tell where they came
    // from.
    $data['example_table']['table']['group'] = t('Example table');
    // Define this as a base table – a table that can be described in itself by
    // views (and not just being brought in as a relationship). In reality this
    // is not very useful for this table, as it isn't really a distinct object of
    // its own, but it makes a good example.
    $data['example_table']['table']['base'] = array(
        // This is the identifier field for the view.
'field' => 'nid',
        'title' => t('Example table'),
        'help' => t('Example table contains example content and can be related to nodes.'),
        'weight' => -10,
    );
    // This table references the {node} table. The declaration below creates an
    // 'implicit' relationship to the node table, so that when 'node' is the base
    // table, the fields are automatically available.
    $data['example_table']['table']['join'] = array(
        // Index this array by the table name to which this table refers.
'node' => array(
            // The primary key in the referenced table.
'left_field' => 'nid',
            // The foreign key in this table.
'field' => 'nid',
        ),
    );
    // Next, describe each of the individual fields in this table to Views. This
    // is done by describing $data['example_table']['FIELD_NAME']. This part of
    // the array may then have further entries:
    //   - title: The label for the table field, as presented in Views.
    //   - help: The description text for the table field.
    //   - relationship: A description of any relationship handler for the table
    //     field.
    //   - field: A description of any field handler for the table field.
    //   - sort: A description of any sort handler for the table field.
    //   - filter: A description of any filter handler for the table field.
    //   - argument: A description of any argument handler for the table field.
    //   - area: A description of any handler for adding content to header,
    //     footer or as no result behaviour.
    //
    // The handler descriptions are described with examples below.
    // Node ID table field.
    $data['example_table']['nid'] = array(
        'title' => t('Example content'),
        'help' => t('Some example content that references a node.'),
        // Define a relationship to the {node} table, so example_table views can
        // add a relationship to nodes. If you want to define a relationship the
        // other direction, use hook_views_data_alter(), or use the 'implicit' join
        // method described above.
'relationship' => array(
            // The name of the table to join with.
'base' => 'node',
            // The name of the field on the joined table.
'base field' => 'nid',
            // 'field' => 'nid' -- see hook_views_data_alter(); not needed here.
'handler' => 'views_handler_relationship',
            'label' => t('Default label for the relationship'),
            'title' => t('Title shown when adding the relationship'),
            'help' => t('More information on this relationship'),
        ),
    );
    // Example plain text field.
    $data['example_table']['plain_text_field'] = array(
        'title' => t('Plain text field'),
        'help' => t('Just a plain text field.'),
        'field' => array(
            'handler' => 'views_handler_field',
            // This is use by the table display plugin.
'click sortable' => TRUE,
        ),
        'sort' => array(
            'handler' => 'views_handler_sort',
        ),
        'filter' => array(
            'handler' => 'views_handler_filter_string',
        ),
        'argument' => array(
            'handler' => 'views_handler_argument_string',
        ),
    );
    // Example numeric text field.
    $data['example_table']['numeric_field'] = array(
        'title' => t('Numeric field'),
        'help' => t('Just a numeric field.'),
        'field' => array(
            'handler' => 'views_handler_field_numeric',
            'click sortable' => TRUE,
        ),
        'filter' => array(
            'handler' => 'views_handler_filter_numeric',
        ),
        'sort' => array(
            'handler' => 'views_handler_sort',
        ),
    );
    // Example boolean field.
    $data['example_table']['boolean_field'] = array(
        'title' => t('Boolean field'),
        'help' => t('Just an on/off field.'),
        'field' => array(
            'handler' => 'views_handler_field_boolean',
            'click sortable' => TRUE,
        ),
        'filter' => array(
            'handler' => 'views_handler_filter_boolean_operator',
            // Note that you can override the field-wide label.
'label' => t('Published'),
            // This setting is used by the boolean filter handler, as possible option.
'type' => 'yes-no',
            // Use boolean_field = 1 instead of boolean_field <> 0 in WHERE statement.
'use equal' => TRUE,
        ),
        'sort' => array(
            'handler' => 'views_handler_sort',
        ),
    );
    // Example timestamp field.
    $data['example_table']['timestamp_field'] = array(
        'title' => t('Timestamp field'),
        'help' => t('Just a timestamp field.'),
        'field' => array(
            'handler' => 'views_handler_field_date',
            'click sortable' => TRUE,
        ),
        'sort' => array(
            'handler' => 'views_handler_sort_date',
        ),
        'filter' => array(
            'handler' => 'views_handler_filter_date',
        ),
    );
    return $data;
}