Chris@0: /**
Chris@0:  * Implements hook_views_data().
Chris@0:  */
Chris@0: function {{ machine_name }}_views_data() {
Chris@0:   // This example describes how to write hook_views_data() for a table defined
Chris@0:   // like this:
Chris@0:   // CREATE TABLE example_table (
Chris@0:   //   nid INT(11) NOT NULL         COMMENT 'Primary key: {node}.nid.',
Chris@0:   //   plain_text_field VARCHAR(32) COMMENT 'Just a plain text field.',
Chris@0:   //   numeric_field INT(11)        COMMENT 'Just a numeric field.',
Chris@0:   //   boolean_field INT(1)         COMMENT 'Just an on/off field.',
Chris@0:   //   timestamp_field INT(8)       COMMENT 'Just a timestamp field.',
Chris@0:   //   langcode VARCHAR(12)         COMMENT 'Language code field.',
Chris@0:   //   PRIMARY KEY(nid)
Chris@0:   // );
Chris@0: 
Chris@0:   // Define the return array.
Chris@0:   $data = [];
Chris@0: 
Chris@0:   // The outermost keys of $data are Views table names, which should usually
Chris@0:   // be the same as the hook_schema() table names.
Chris@0:   $data['example_table'] = [];
Chris@0: 
Chris@0:   // The value corresponding to key 'table' gives properties of the table
Chris@0:   // itself.
Chris@0:   $data['example_table']['table'] = [];
Chris@0: 
Chris@0:   // Within 'table', the value of 'group' (translated string) is used as a
Chris@0:   // prefix in Views UI for this table's fields, filters, etc. When adding
Chris@0:   // a field, filter, etc. you can also filter by the group.
Chris@0:   $data['example_table']['table']['group'] = t('Example table');
Chris@0: 
Chris@0:   // Within 'table', the value of 'provider' is the module that provides schema
Chris@0:   // or the entity type that causes the table to exist. Setting this ensures
Chris@0:   // that views have the correct dependencies. This is automatically set to the
Chris@0:   // module that implements hook_views_data().
Chris@0:   $data['example_table']['table']['provider'] = 'example_module';
Chris@0: 
Chris@0:   // Some tables are "base" tables, meaning that they can be the base tables
Chris@0:   // for views. Non-base tables can only be brought in via relationships in
Chris@0:   // views based on other tables. To define a table to be a base table, add
Chris@0:   // key 'base' to the 'table' array:
Chris@0:   $data['example_table']['table']['base'] = [
Chris@0:     // Identifier (primary) field in this table for Views.
Chris@0:     'field' => 'nid',
Chris@0:     // Label in the UI.
Chris@0:     'title' => t('Example table'),
Chris@0:     // Longer description in the UI. Required.
Chris@0:     'help' => t('Example table contains example content and can be related to nodes.'),
Chris@0:     'weight' => -10,
Chris@0:   ];
Chris@0: 
Chris@0:   // Some tables have an implicit, automatic relationship to other tables,
Chris@0:   // meaning that when the other table is available in a view (either as the
Chris@0:   // base table or through a relationship), this table's fields, filters, etc.
Chris@0:   // are automatically made available without having to add an additional
Chris@0:   // relationship. To define an implicit relationship that will make your
Chris@0:   // table automatically available when another table is present, add a 'join'
Chris@0:   // section to your 'table' section. Note that it is usually only a good idea
Chris@0:   // to do this for one-to-one joins, because otherwise your automatic join
Chris@0:   // will add more rows to the view. It is also not a good idea to do this if
Chris@0:   // most views won't need your table -- if that is the case, define a
Chris@0:   // relationship instead (see below).
Chris@0:   //
Chris@0:   // If you've decided an automatic join is a good idea, here's how to do it;
Chris@0:   // the resulting SQL query will look something like this:
Chris@0:   //   ... FROM example_table et ... JOIN node_field_data nfd
Chris@0:   //   ON et.nid = nfd.nid AND ('extra' clauses will be here) ...
Chris@0:   // although the table aliases will be different.
Chris@0:   $data['example_table']['table']['join'] = [
Chris@0:     // Within the 'join' section, list one or more tables to automatically
Chris@0:     // join to. In this example, every time 'node_field_data' is available in
Chris@0:     // a view, 'example_table' will be too. The array keys here are the array
Chris@0:     // keys for the other tables, given in their hook_views_data()
Chris@0:     // implementations. If the table listed here is from another module's
Chris@0:     // hook_views_data() implementation, make sure your module depends on that
Chris@0:     // other module.
Chris@0:     'node_field_data' => [
Chris@0:       // Primary key field in node_field_data to use in the join.
Chris@0:       'left_field' => 'nid',
Chris@0:       // Foreign key field in example_table to use in the join.
Chris@0:       'field' => 'nid',
Chris@0:       // 'extra' is an array of additional conditions on the join.
Chris@0:       'extra' => [
Chris@0:         0 => [
Chris@0:           // Adds AND node_field_data.published = TRUE to the join.
Chris@0:           'field' => 'published',
Chris@0:           'value' => TRUE,
Chris@0:         ],
Chris@0:         1 => [
Chris@0:           // Adds AND example_table.numeric_field = 1 to the join.
Chris@0:           'left_field' => 'numeric_field',
Chris@0:           'value' => 1,
Chris@0:           // If true, the value will not be surrounded in quotes.
Chris@0:           'numeric' => TRUE,
Chris@0:         ],
Chris@0:         2 => [
Chris@0:           // Adds AND example_table.boolean_field <>
Chris@0:           // node_field_data.published to the join.
Chris@0:           'field' => 'published',
Chris@0:           'left_field' => 'boolean_field',
Chris@0:           // The operator used, Defaults to "=".
Chris@0:           'operator' => '!=',
Chris@0:         ],
Chris@0:       ],
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // You can also do a more complex join, where in order to get to a certain
Chris@0:   // base table defined in a hook_views_data() implementation, you will join
Chris@0:   // to a different table that Views knows how to auto-join to the base table.
Chris@0:   // For instance, if another module that your module depends on had
Chris@0:   // defined a table 'foo' with an automatic join to 'node_field_table' (as
Chris@0:   // shown above), you could join to 'node_field_table' via the 'foo' table.
Chris@0:   // Here's how to do this, and the resulting SQL query would look something
Chris@0:   // like this:
Chris@0:   //   ... FROM example_table et ... JOIN foo foo
Chris@0:   //   ON et.nid = foo.nid AND ('extra' clauses will be here) ...
Chris@0:   //   JOIN node_field_data nfd ON (definition of the join from the foo
Chris@0:   //   module goes here) ...
Chris@0:   // although the table aliases will be different.
Chris@0:   $data['example_table']['table']['join']['node_field_data'] = [
Chris@0:     // 'node_field_data' above is the base we're joining to in Views.
Chris@0:     // 'left_table' is the table we're actually joining to, in order to get to
Chris@0:     // 'node_field_data'. It has to be something that Views knows how to join
Chris@0:     // to 'node_field_data'.
Chris@0:     'left_table' => 'foo',
Chris@0:     'left_field' => 'nid',
Chris@0:     'field' => 'nid',
Chris@0:     // 'extra' is an array of additional conditions on the join.
Chris@0:     'extra' => [
Chris@0:       // This syntax matches additional fields in the two tables:
Chris@0:       // ... AND foo.langcode = example_table.langcode ...
Chris@0:       ['left_field' => 'langcode', 'field' => 'langcode'],
Chris@0:       // This syntax adds a condition on our table. 'operator' defaults to
Chris@0:       // '=' for non-array values, or 'IN' for array values.
Chris@0:       // ... AND example_table.numeric_field > 0 ...
Chris@0:       ['field' => 'numeric_field', 'value' => 0, 'numeric' => TRUE, 'operator' => '>'],
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Other array elements at the top level of your table's array describe
Chris@0:   // individual database table fields made available to Views. The array keys
Chris@0:   // are the names (unique within the table) used by Views for the fields,
Chris@0:   // usually equal to the database field names.
Chris@0:   //
Chris@0:   // Each field entry must have the following elements:
Chris@0:   // - title: Translated label for the field in the UI.
Chris@0:   // - help: Description of the field in the UI.
Chris@0:   //
Chris@0:   // Each field entry may also have one or more of the following elements,
Chris@0:   // describing "handlers" (plugins) for the field:
Chris@0:   // - relationship: Specifies a handler that allows this field to be used
Chris@0:   //   to define a relationship to another table in Views.
Chris@0:   // - field: Specifies a handler to make it available to Views as a field.
Chris@0:   // - filter: Specifies a handler to make it available to Views as a filter.
Chris@0:   // - sort: Specifies a handler to make it available to Views as a sort.
Chris@0:   // - argument: Specifies a handler to make it available to Views as an
Chris@0:   //   argument, or contextual filter as it is known in the UI.
Chris@0:   // - area: Specifies a handler to make it available to Views to add content
Chris@0:   //   to the header, footer, or as no result behavior.
Chris@0:   //
Chris@0:   // Note that when specifying handlers, you must give the handler plugin ID
Chris@0:   // and you may also specify overrides for various settings that make up the
Chris@0:   // plugin definition. See examples below; the Boolean example demonstrates
Chris@0:   // setting overrides.
Chris@0: 
Chris@0:   // Node ID field, exposed as relationship only, since it is a foreign key
Chris@0:   // in this table.
Chris@0:   $data['example_table']['nid'] = [
Chris@0:     'title' => t('Example content'),
Chris@0:     'help' => t('Relate example content to the node content'),
Chris@0: 
Chris@0:     // Define a relationship to the node_field_data table, so views whose
Chris@0:     // base table is example_table can add a relationship to nodes. To make a
Chris@0:     // relationship in the other direction, you can:
Chris@0:     // - Use hook_views_data_alter() -- see the function body example on that
Chris@0:     //   hook for details.
Chris@0:     // - Use the implicit join method described above.
Chris@0:     'relationship' => [
Chris@0:       // Views name of the table to join to for the relationship.
Chris@0:       'base' => 'node_field_data',
Chris@0:       // Database field name in the other table to join on.
Chris@0:       'base field' => 'nid',
Chris@0:       // ID of relationship handler plugin to use.
Chris@0:       'id' => 'standard',
Chris@0:       // Default label for relationship in the UI.
Chris@0:       'label' => t('Example node'),
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Plain text field, exposed as a field, sort, filter, and argument.
Chris@0:   $data['example_table']['plain_text_field'] = [
Chris@0:     'title' => t('Plain text field'),
Chris@0:     'help' => t('Just a plain text field.'),
Chris@0: 
Chris@0:     'field' => [
Chris@0:       // ID of field handler plugin to use.
Chris@0:       'id' => 'standard',
Chris@0:     ],
Chris@0: 
Chris@0:     'sort' => [
Chris@0:       // ID of sort handler plugin to use.
Chris@0:       'id' => 'standard',
Chris@0:     ],
Chris@0: 
Chris@0:     'filter' => [
Chris@0:       // ID of filter handler plugin to use.
Chris@0:       'id' => 'string',
Chris@0:     ],
Chris@0: 
Chris@0:     'argument' => [
Chris@0:       // ID of argument handler plugin to use.
Chris@0:       'id' => 'string',
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Numeric field, exposed as a field, sort, filter, and argument.
Chris@0:   $data['example_table']['numeric_field'] = [
Chris@0:     'title' => t('Numeric field'),
Chris@0:     'help' => t('Just a numeric field.'),
Chris@0: 
Chris@0:     'field' => [
Chris@0:       // ID of field handler plugin to use.
Chris@0:       'id' => 'numeric',
Chris@0:     ],
Chris@0: 
Chris@0:     'sort' => [
Chris@0:       // ID of sort handler plugin to use.
Chris@0:       'id' => 'standard',
Chris@0:     ],
Chris@0: 
Chris@0:     'filter' => [
Chris@0:       // ID of filter handler plugin to use.
Chris@0:       'id' => 'numeric',
Chris@0:     ],
Chris@0: 
Chris@0:     'argument' => [
Chris@0:       // ID of argument handler plugin to use.
Chris@0:       'id' => 'numeric',
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Boolean field, exposed as a field, sort, and filter. The filter section
Chris@0:   // illustrates overriding various settings.
Chris@0:   $data['example_table']['boolean_field'] = [
Chris@0:     'title' => t('Boolean field'),
Chris@0:     'help' => t('Just an on/off field.'),
Chris@0: 
Chris@0:     'field' => [
Chris@0:       // ID of field handler plugin to use.
Chris@0:       'id' => 'boolean',
Chris@0:     ],
Chris@0: 
Chris@0:     'sort' => [
Chris@0:       // ID of sort handler plugin to use.
Chris@0:       'id' => 'standard',
Chris@0:     ],
Chris@0: 
Chris@0:     'filter' => [
Chris@0:       // ID of filter handler plugin to use.
Chris@0:       'id' => 'boolean',
Chris@0:       // Override the generic field title, so that the filter uses a different
Chris@0:       // label in the UI.
Chris@0:       'label' => t('Published'),
Chris@0:       // Override the default BooleanOperator filter handler's 'type' setting,
Chris@0:       // to display this as a "Yes/No" filter instead of a "True/False" filter.
Chris@0:       'type' => 'yes-no',
Chris@0:       // Override the default Boolean filter handler's 'use_equal' setting, to
Chris@0:       // make the query use 'boolean_field = 1' instead of 'boolean_field <> 0'.
Chris@0:       'use_equal' => TRUE,
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Integer timestamp field, exposed as a field, sort, and filter.
Chris@0:   $data['example_table']['timestamp_field'] = [
Chris@0:     'title' => t('Timestamp field'),
Chris@0:     'help' => t('Just a timestamp field.'),
Chris@0: 
Chris@0:     'field' => [
Chris@0:       // ID of field handler plugin to use.
Chris@0:       'id' => 'date',
Chris@0:     ],
Chris@0: 
Chris@0:     'sort' => [
Chris@0:       // ID of sort handler plugin to use.
Chris@0:       'id' => 'date',
Chris@0:     ],
Chris@0: 
Chris@0:     'filter' => [
Chris@0:       // ID of filter handler plugin to use.
Chris@0:       'id' => 'date',
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   // Area example. Areas are not generally associated with actual data
Chris@0:   // tables and fields. This example is from views_views_data(), which defines
Chris@0:   // the "Global" table (not really a table, but a group of Fields, Filters,
Chris@0:   // etc. that are grouped into section "Global" in the UI). Here's the
Chris@0:   // definition of the generic "Text area":
Chris@0:   $data['views']['area'] = [
Chris@0:     'title' => t('Text area'),
Chris@0:     'help' => t('Provide markup text for the area.'),
Chris@0:     'area' => [
Chris@0:       // ID of the area handler plugin to use.
Chris@0:       'id' => 'text',
Chris@0:     ],
Chris@0:   ];
Chris@0: 
Chris@0:   return $data;
Chris@0: }