crm.fsf.org/20131203/files/sites/all/modules-new/views/help/api-example.html

   1
   2 For the new table defined by the Node example module to be understood by the views module you need to create a node_example.views.inc file that describes the table and its relationships to the rest of the database.  In order for views to know that this file is to be loaded you need to implement hook_views_api.  This is done by adding the following function into your node_example.module file
   3
   4 <pre>
   5 &lt;?php
   6 /**
   7  * Implements hook_views_api().
   8  *
   9  * This tells drupal that there is Views integration file named
  10  * module-name.views.inc
  11  */
  12 function node_example_views_api() {
  13   // Note that you can include 'path' in this array so that your views.inc
  14   // file can be stored in a different location.
  15   return array(
  16     'api' => 2.0
  17   );
  18 }
  19 ?&gt;
  20 </pre>
  21
  22 Below is the contents of a simple node_example.views.inc file that allows you to create views that include the new color and quantity information.
  23
  24 <pre>
  25 &lt;?php
  26
  27 /**
  28  * This file is used to tell the views module about the new node_example table.
  29  *
  30  * Database definition:
  31  * @code
  32  *   CREATE TABLE node_example (
  33  *     vid int(10) unsigned NOT NULL default '0',
  34  *     nid int(10) unsigned NOT NULL default '0',
  35  *     color varchar(255) NOT NULL default '',
  36  *     quantity int(10) unsigned NOT NULL default '0',
  37  *     PRIMARY KEY (vid, nid),
  38  *     KEY `node_example_nid` (nid)
  39  *   )
  40  * @endcode
  41  */
  42
  43 function node_example_views_data()  {
  44   // Basic table information.
  45
  46   // ----------------------------------------------------------------
  47   // node_example table
  48   //  New group within Views called 'Example'
  49   //  The group will appear in the UI in the dropdown tha allows you
  50   //  to narrow down which fields and filters are available.
  51
  52   $data = array();
  53   $data['node_example']['table']['group']  = t('Example');
  54
  55   // Let Views know that our example table joins to the 'node'
  56   // base table. This means it will be available when listing
  57   // nodes and automatically make its fields appear.
  58   //
  59   // We also show up for node revisions.
  60   $data['node_example']['table']['join'] = array(
  61     'node_revisions' => array(
  62       'left_field' => 'vid',
  63       'field' => 'vid',
  64     ),
  65     'node' => array(
  66       'left_field' => 'vid',
  67       'field' => 'vid',
  68     ),
  69   );
  70
  71   // quantity
  72   $data['node_example']['quantity'] = array(
  73     'title' => t('Quantity'),
  74     'help' => t('Quantity of items.'),
  75     'field' => array(
  76       'handler' => 'views_handler_field_numeric',
  77       'click sortable' => TRUE,
  78      ),
  79     'filter' => array(
  80       'handler' => 'views_handler_filter_numeric',
  81     ),
  82     'sort' => array(
  83       'handler' => 'views_handler_sort',
  84     ),
  85   );
  86
  87   // Color
  88   $data['node_example']['color'] = array(
  89     'title' => t('Color'),
  90     'help' => t('Color of item.'),
  91
  92     'field' => array(
  93       'handler' => 'views_handler_field',
  94       'click sortable' => TRUE,
  95      ),
  96      'filter' => array(
  97       'handler' => 'views_handler_filter_string',
  98      ),
  99      'argument' => array(
 100        'handler' => 'views_handler_argument_string',
 101      ),
 102      'sort' => array(
 103       'handler' => 'views_handler_sort',
 104      ),
 105   );
 106
 107   return $data;
 108 }
 109
 110 ?&gt;
 111 </pre>
 112
 113 Some notes on usage:
 114
 115 Within Views, click on the Add tab.  You have a number of type options here.  Normally you would select either 'Node' (if you only want to display information on current nodes) or 'Node revision' (if you want to display information on all revisions of the nodes)
 116
 117 With this configuration you always pull out of the database, data for every single node, whether or not it has color and quantity information.  To display information on just those nodes that have color and quantity information you can use a filter so that only nodes which don't have a NULL color or a NULL quantity are displayed.
 118
 119 <h3>Type/relationship extension</h3>
 120
 121 When your tables have first class data, you will often need to have own View types and View relationships defined.  With the current node_example table this isn't required although I try to justify it below on an efficiency basis. See [[http://groups.drupal.org/node/17236#comment-58980|this discussion]] as to why it isn't justified.
 122
 123 Pulling data out of the database for every node when you only want data for the new Example node type is inefficient.  To reduce the initial data extraction to just that relating to the new Example nodes requires that you make the node_example table the base table.  This can be done by adding the following code into the node_example.views.inc file just before the 'return $data;'
 124
 125 <pre>
 126 &lt;?php
 127
 128 //  **** Begin optional extra for type and relationships ****
 129
 130   //  Use node_example as a new base table
 131   //     by creating a new views type called 'Node example'
 132   //  This allows it to be selected as the 'view type'
 133   //          when you initially add a new view.
 134   $data['node_example']['table']['base'] = array(
 135     'field' => 'vid',
 136     'title' => t('Node example'),
 137     'help' => t("Node example type with color and quantity information."),
 138     'weight' => -9,
 139   );
 140
 141   // When using the new 'Node example' type you need to use relationships
 142   //   to access fields in other tables.
 143
 144   // Relationship to the 'Node revision' table
 145   $data['node_example']['vid'] = array(
 146     'title' => t('Node revision'),
 147     'help' => t('The particular node revision the color and quantity is attached to'),
 148     'relationship' => array(
 149       'label' => t('Node revision'),
 150       'base' => 'node_revisions',
 151       'base field' => 'vid',
 152       // This allows us to not show this relationship if the base is already
 153       // node_revisions so users won't create circular relationships.
 154       'skip base' => array('node', 'node_revisions'),
 155     ),
 156   );
 157
 158   // Relationship to the 'Node' table
 159   $data['node_example']['nid'] = array(
 160     'title' => t('Node'),
 161     'help' => t('The particular node the color and quantity is attached to'),
 162     'relationship' => array(
 163       'label' => t('Node'),
 164       'base' => 'node',
 165       'base field' => 'nid',
 166       // This allows us to not show this relationship if the base is already
 167       // node so users won't create circular relationships.
 168       'skip base' => array('node', 'node_revisions'),
 169     ),
 170   );
 171
 172 //  **** End optional extra for type and relationships ****
 173
 174 ?&gt;
 175 </pre>
 176
 177 The above code adds a new 'Node example' to the view types that can be selected within the Add tab window of views.  Selecting this sets the node_example table to be the base table.
 178
 179 If you select 'Node example' as view type, when you initially go into the edit window of views you will find  the only fields available are the color and quantity fields.  To get fields from other tables you need to add a relationship.  Relationships may be found at the top in the same column as the fields.