Views' hooks


Detailed Description

Hooks that can be implemented by other modules in order to implement the Views API.


Functions

 hook_views_data ()
 Describe table structure to Views.
 hook_views_plugins ()
 The full documentation for this hook is now in the advanced help.
 hook_views_handlers ()
 Register handler, file and parent information so that handlers can be loaded only on request.
 hook_views_api ()
 Register View API information.
 hook_views_default_views ()
 This hook allows modules to provide their own views which can either be used as-is or as a "starter" for users to build from.
 hook_views_default_views_alter (&$views)
 This hook is called right before all default views are cached to the database.
 hook_views_convert ()
 Stub hook documentation.
 hook_views_query_substitutions ()
 Stub hook documentation.
 hook_views_pre_view (&$view, &$display_id, &$args)
 This hook is called at the very beginning of views processing, before anything is done.
 hook_views_pre_build (&$view)
 This hook is called right before the build process, but after displays are attached and the display performs its pre_execute phase.
 hook_views_pre_execute (&$view)
 This hook is called right before the execute process.
 hook_views_pre_render (&$view)
 This hook is called right before the render process.
 hook_views_post_render (&$view, &$output, &$cache)
 Post process any rendered data.
 hook_views_query_alter (&$view, &$query)
 Stub hook documentation.
 hook_views_admin_links_alter (&$links, $view)
 This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 hook_views_preview_info_alter (&$rows, $view)
 This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.


Function Documentation

hook_views_admin_links_alter ( &$  links,
view 
)

This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.

This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

Alter the links that appear over a view. They are in a format suitable for theme('links').

Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS a reference in PHP5, and can be modified. Please be careful with it.

See also:
theme_links

Definition at line 635 of file docs.php.

00635                                                       {
00636   // example code here
00637 }

hook_views_api (  ) 

Register View API information.

This is required for your module to have its include files loaded; for example, when implementing hook_views_default_views().

Returns:
An array with the following possible keys:
  • api: (required) The version of the Views API the module implements.
  • path: (optional) If includes are stored somewhere other than within the root module directory or a subdirectory called includes, specify its path here.

Definition at line 244 of file docs.php.

00244                           {
00245   return array(
00246     'api' => 2,
00247     'path' => drupal_get_path('module', 'example') . '/includes/views', 
00248   );
00249 }

hook_views_convert (  ) 

Stub hook documentation.

This hook should be placed in MODULENAME.views_convert.inc and it will be auto-loaded. This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

Definition at line 526 of file docs.php.

00526                               {
00527   // example code here
00528 }

hook_views_data (  ) 

Describe table structure to Views.

This hook should be placed in MODULENAME.views.inc and it will be auto-loaded. This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

The full documentation for this hook is in the advanced help. http://views-help.doc.logrus.com/help/views/api-tables

Definition at line 74 of file docs.php.

00074                            {
00075   // This example describes how to write hook_views_data() for the following
00076   // table:
00077   //
00078   // CREATE TABLE example_table (
00079   //   nid INT(11) NOT NULL         COMMENT 'Primary key; refers to {node}.nid.',
00080   //   plain_text_field VARCHAR(32) COMMENT 'Just a plain text field.',
00081   //   numeric_field INT(11)        COMMENT 'Just a numeric field.',
00082   //   boolean_field INT(1)         COMMENT 'Just an on/off field.',
00083   //   timestamp_field INT(8)       COMMENT 'Just a timestamp field.',
00084   //   PRIMARY KEY(nid)
00085   // );
00086 
00087   // The 'group' index will be used as a prefix in the UI for any of this
00088   // table's fields, sort criteria, etc. so it's easy to tell where they came
00089   // from.
00090   $data['example_table']['table']['group'] = t('Example table');
00091 
00092   // Define this as a base table. In reality this is not very useful for
00093   // this table, as it isn't really a distinct object of its own, but
00094   // it makes a good example.
00095   $data['example_table']['table']['base'] = array(
00096     'field' => 'nid',
00097     'title' => t('Example table'),
00098     'help' => t("Example table contains example content and can be related to nodes."),
00099     'weight' => -10,
00100   );
00101 
00102   // This table references the {node} table.
00103   // This creates an 'implicit' relationship to the node table, so that when 'Node'
00104   // is the base table, the fields are automatically available.
00105   $data['example_table']['table']['join'] = array(
00106     // Index this array by the table name to which this table refers.
00107     // 'left_field' is the primary key in the referenced table.
00108     // 'field' is the foreign key in this table.
00109     'node' => array(
00110       'left_field' => 'nid',
00111       'field' => 'nid',
00112     ),
00113   );
00114 
00115   // Next, describe each of the individual fields in this table to Views. For
00116   // each field, you may define what field, sort, argument, and/or filter
00117   // handlers it supports. This will determine where in the Views interface you
00118   // may use the field.
00119 
00120   // Node ID field.
00121   $data['example_table']['nid'] = array(
00122     'title' => t('Example content'),
00123     'help' => t('Some example content that references a node.'),
00124     // Because this is a foreign key to the {node} table. This allows us to
00125     // have, when the view is configured with this relationship, all the fields
00126     // for the related node available.
00127     'relationship' => array(
00128       'base' => 'node',
00129       'field' => 'nid',
00130       'handler' => 'views_handler_relationship',
00131       'label' => t('Example node'),
00132     ),
00133   );
00134 
00135   // Example plain text field.
00136   $data['example_table']['plain_text_field'] = array(
00137     'title' => t('Plain text field'),
00138     'help' => t('Just a plain text field.'),
00139     'field' => array(
00140       'handler' => 'views_handler_field',
00141       'click sortable' => TRUE,
00142     ),
00143     'sort' => array(
00144       'handler' => 'views_handler_sort',
00145     ),
00146     'filter' => array(
00147       'handler' => 'views_handler_filter_string',
00148     ),
00149     'argument' => array(
00150       'handler' => 'views_handler_argument_string',
00151     ),
00152   );
00153 
00154   // Example numeric text field.
00155   $data['example_table']['numeric_field'] = array(
00156     'title' => t('Numeric field'),
00157     'help' => t('Just a numeric field.'),
00158     'field' => array(
00159       'handler' => 'views_handler_field_numeric',
00160       'click sortable' => TRUE,
00161      ),
00162     'filter' => array(
00163       'handler' => 'views_handler_filter_numeric',
00164     ),
00165     'sort' => array(
00166       'handler' => 'views_handler_sort',
00167     ),
00168   );
00169 
00170   // Example boolean field.
00171   $data['example_table']['boolean_field'] = array(
00172     'title' => t('Boolean field'),
00173     'help' => t('Just an on/off field.'),
00174     'field' => array(
00175       'handler' => 'views_handler_field_boolean',
00176       'click sortable' => TRUE,
00177     ),
00178     'filter' => array(
00179       'handler' => 'views_handler_filter_boolean_operator',
00180       'label' => t('Published'),
00181       'type' => 'yes-no',
00182     ),
00183     'sort' => array(
00184       'handler' => 'views_handler_sort',
00185     ),
00186   );
00187 
00188   // Example timestamp field.
00189   $data['example_table']['timestamp_field'] = array(
00190     'title' => t('Timestamp field'),
00191     'help' => t('Just a timestamp field.'),
00192     'field' => array(
00193       'handler' => 'views_handler_field_date',
00194       'click sortable' => TRUE,
00195     ),
00196     'sort' => array(
00197       'handler' => 'views_handler_sort_date',
00198     ),
00199     'filter' => array(
00200       'handler' => 'views_handler_filter_date',
00201     ),
00202   );
00203 
00204   return $data;
00205 }

hook_views_default_views (  ) 

This hook allows modules to provide their own views which can either be used as-is or as a "starter" for users to build from.

This hook should be placed in MODULENAME.views_default.inc and it will be auto-loaded. This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

The $view->disabled boolean flag indicates whether the View should be enabled or disabled by default.

Returns:
An associative array containing the structures of views, as generated from the Export tab, keyed by the view name. A best practice is to go through and add t() to all title and label strings, with the exception of menu strings.

Definition at line 268 of file docs.php.

00268                                     {
00269   // Begin copy and paste of output from the Export tab of a view.
00270   $view = new view;
00271   $view->name = 'frontpage';
00272   $view->description = t('Emulates the default Drupal front page; you may set the default home page path to this view to make it your front page.');
00273   $view->tag = t('default');
00274   $view->view_php = '';
00275   $view->base_table = 'node';
00276   $view->is_cacheable = '0';
00277   $view->api_version = 2;
00278   $view->disabled = FALSE; // Edit this to true to make a default view disabled initially
00279   $view->display = array();
00280     $display = new views_display;
00281     $display->id = 'default';
00282     $display->display_title = t('Defaults');
00283     $display->display_plugin = 'default';
00284     $display->position = '1';
00285     $display->display_options = array (
00286     'style_plugin' => 'default',
00287     'style_options' =>
00288     array (
00289     ),
00290     'row_plugin' => 'node',
00291     'row_options' =>
00292     array (
00293       'teaser' => 1,
00294       'links' => 1,
00295     ),
00296     'relationships' =>
00297     array (
00298     ),
00299     'fields' =>
00300     array (
00301     ),
00302     'sorts' =>
00303     array (
00304       'sticky' =>
00305       array (
00306         'id' => 'sticky',
00307         'table' => 'node',
00308         'field' => 'sticky',
00309         'order' => 'ASC',
00310       ),
00311       'created' =>
00312       array (
00313         'id' => 'created',
00314         'table' => 'node',
00315         'field' => 'created',
00316         'order' => 'ASC',
00317         'relationship' => 'none',
00318         'granularity' => 'second',
00319       ),
00320     ),
00321     'arguments' =>
00322     array (
00323     ),
00324     'filters' =>
00325     array (
00326       'promote' =>
00327       array (
00328         'id' => 'promote',
00329         'table' => 'node',
00330         'field' => 'promote',
00331         'operator' => '=',
00332         'value' => '1',
00333         'group' => 0,
00334         'exposed' => false,
00335         'expose' =>
00336         array (
00337           'operator' => false,
00338           'label' => '',
00339         ),
00340       ),
00341       'status' =>
00342       array (
00343         'id' => 'status',
00344         'table' => 'node',
00345         'field' => 'status',
00346         'operator' => '=',
00347         'value' => '1',
00348         'group' => 0,
00349         'exposed' => false,
00350         'expose' =>
00351         array (
00352           'operator' => false,
00353           'label' => '',
00354         ),
00355       ),
00356     ),
00357     'items_per_page' => 10,
00358     'use_pager' => '1',
00359     'pager_element' => 0,
00360     'title' => '',
00361     'header' => '',
00362     'header_format' => '1',
00363     'footer' => '',
00364     'footer_format' => '1',
00365     'empty' => '',
00366     'empty_format' => '1',
00367   );
00368   $view->display['default'] = $display;
00369     $display = new views_display;
00370     $display->id = 'page';
00371     $display->display_title = t('Page');
00372     $display->display_plugin = 'page';
00373     $display->position = '2';
00374     $display->display_options = array (
00375     'defaults' =>
00376     array (
00377       'access' => true,
00378       'title' => true,
00379       'header' => true,
00380       'header_format' => true,
00381       'header_empty' => true,
00382       'footer' => true,
00383       'footer_format' => true,
00384       'footer_empty' => true,
00385       'empty' => true,
00386       'empty_format' => true,
00387       'items_per_page' => true,
00388       'offset' => true,
00389       'use_pager' => true,
00390       'pager_element' => true,
00391       'link_display' => true,
00392       'php_arg_code' => true,
00393       'exposed_options' => true,
00394       'style_plugin' => true,
00395       'style_options' => true,
00396       'row_plugin' => true,
00397       'row_options' => true,
00398       'relationships' => true,
00399       'fields' => true,
00400       'sorts' => true,
00401       'arguments' => true,
00402       'filters' => true,
00403       'use_ajax' => true,
00404       'distinct' => true,
00405     ),
00406     'relationships' =>
00407     array (
00408     ),
00409     'fields' =>
00410     array (
00411     ),
00412     'sorts' =>
00413     array (
00414     ),
00415     'arguments' =>
00416     array (
00417     ),
00418     'filters' =>
00419     array (
00420     ),
00421     'path' => 'frontpage',
00422   );
00423   $view->display['page'] = $display;
00424     $display = new views_display;
00425     $display->id = 'feed';
00426     $display->display_title = t('Feed');
00427     $display->display_plugin = 'feed';
00428     $display->position = '3';
00429     $display->display_options = array (
00430     'defaults' =>
00431     array (
00432       'access' => true,
00433       'title' => false,
00434       'header' => true,
00435       'header_format' => true,
00436       'header_empty' => true,
00437       'footer' => true,
00438       'footer_format' => true,
00439       'footer_empty' => true,
00440       'empty' => true,
00441       'empty_format' => true,
00442       'use_ajax' => true,
00443       'items_per_page' => true,
00444       'offset' => true,
00445       'use_pager' => true,
00446       'pager_element' => true,
00447       'use_more' => true,
00448       'distinct' => true,
00449       'link_display' => true,
00450       'php_arg_code' => true,
00451       'exposed_options' => true,
00452       'style_plugin' => false,
00453       'style_options' => false,
00454       'row_plugin' => false,
00455       'row_options' => false,
00456       'relationships' => true,
00457       'fields' => true,
00458       'sorts' => true,
00459       'arguments' => true,
00460       'filters' => true,
00461     ),
00462     'relationships' =>
00463     array (
00464     ),
00465     'fields' =>
00466     array (
00467     ),
00468     'sorts' =>
00469     array (
00470     ),
00471     'arguments' =>
00472     array (
00473     ),
00474     'filters' =>
00475     array (
00476     ),
00477     'displays' =>
00478     array (
00479       'default' => 'default',
00480       'page' => 'page',
00481     ),
00482     'style_plugin' => 'rss',
00483     'style_options' =>
00484     array (
00485       'mission_description' => 1,
00486       'description' => '',
00487     ),
00488     'row_plugin' => 'node_rss',
00489     'row_options' =>
00490     array (
00491       'item_length' => 'default',
00492     ),
00493     'path' => 'rss.xml',
00494     'title' => t('Front page feed'),
00495   );
00496   $view->display['feed'] = $display;
00497   // End copy and paste of Export tab output.
00498 
00499   // Add view to list of views to provide.
00500   $views[$view->name] = $view;
00501 
00502   // ...Repeat all of the above for each view the module should provide.
00503 
00504   // At the end, return array of default views.
00505   return $views;
00506 }

hook_views_default_views_alter ( &$  views  ) 

This hook is called right before all default views are cached to the database.

It takes a keyed array of views by reference.

Definition at line 512 of file docs.php.

00512                                                  {
00513   if (isset($views['taxonomy_term'])) {
00514     $views['taxonomy_term']->set_display('default');
00515     $views['taxonomy_term']->display_handler->set_option('title', 'Categories');
00516   }
00517 }

hook_views_handlers (  ) 

Register handler, file and parent information so that handlers can be loaded only on request.

The full documentation for this hook is in the advanced help.

Definition at line 228 of file docs.php.

00228                                {
00229   // example code here
00230 }

hook_views_plugins (  ) 

The full documentation for this hook is now in the advanced help.

This hook should be placed in MODULENAME.views.inc and it will be auto-loaded. This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

This is a stub list as a reminder that this needs to be doc'd and is not used in views anywhere so might not be remembered when this is formally documented:

Definition at line 218 of file docs.php.

00218                               {
00219   // example code here
00220 }

hook_views_post_render ( &$  view,
&$  output,
&$  cache 
)

Post process any rendered data.

This can be valuable to be able to cache a view and still have some level of dynamic output. In an ideal world, the actual output will include HTML comment based tokens, and then the post process can replace those tokens.

Example usage. If it is known that the view is a node view and that the primary field will be a nid, you can do something like this:

And then in the post render, create an array with the text that should go there:

strtr($output, array('', 'output for FIELD of nid 1');

All of the cached result data will be available in $view->result, as well, so all ids used in the query should be discoverable.

This hook can be utilized by themes.

Definition at line 606 of file docs.php.

00606                                                            {
00607 
00608 }

hook_views_pre_build ( &$  view  ) 

This hook is called right before the build process, but after displays are attached and the display performs its pre_execute phase.

Adding output to the view cam be accomplished by placing text on $view->attachment_before and $view->attachment_after

Definition at line 555 of file docs.php.

00555                                       {
00556   // example code here
00557 }

hook_views_pre_execute ( &$  view  ) 

This hook is called right before the execute process.

The query is now fully built, but it has not yet been run through db_rewrite_sql.

Adding output to the view cam be accomplished by placing text on $view->attachment_before and $view->attachment_after

Definition at line 566 of file docs.php.

00566                                         {
00567   // example code here
00568 }

hook_views_pre_render ( &$  view  ) 

This hook is called right before the render process.

The query has been executed, and the pre_render() phase has already happened for handlers, so all data should be available.

Adding output to the view cam be accomplished by placing text on $view->attachment_before and $view->attachment_after

This hook can be utilized by themes.

Definition at line 580 of file docs.php.

00580                                        {
00581   // example code here
00582 }

hook_views_pre_view ( &$  view,
&$  display_id,
&$  args 
)

This hook is called at the very beginning of views processing, before anything is done.

Adding output to the view cam be accomplished by placing text on $view->attachment_before and $view->attachment_after

Definition at line 544 of file docs.php.

00544                                                            {
00545   // example code here
00546 }

hook_views_preview_info_alter ( &$  rows,
view 
)

This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.

This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

Alter the rows that appear with a view, which includes path and query information. The rows are suitable for theme('table').

Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS a reference in PHP5, and can be modified. Please be careful with it.

See also:
theme_table

Definition at line 652 of file docs.php.

00652                                                       {
00653   // example code here
00654 }

hook_views_query_alter ( &$  view,
&$  query 
)

Stub hook documentation.

This hook should be placed in MODULENAME.views.inc and it will be auto-loaded. This must either be in the same directory as the .module file or in a subdirectory named 'includes'.

Definition at line 618 of file docs.php.

00618                                                  {
00619   // example code here
00620 }

hook_views_query_substitutions (  ) 

Stub hook documentation.

Definition at line 533 of file docs.php.

00533                                           {
00534   // example code here
00535 }


Generated on Mon Nov 30 15:06:03 2009 for Views by  doxygen 1.4.7