docs.php in Views (for Drupal 7) 6.3
Same filename and directory in other branches
This file contains no working PHP code; it exists to provide additional documentation for doxygen as well as to document hooks in the standard Drupal manner.
File
docs/docs.phpView source
<?php
/**
* @file
* This file contains no working PHP code; it exists to provide additional documentation
* for doxygen as well as to document hooks in the standard Drupal manner.
*/
/**
* @mainpage Views 2 API Manual
*
* Much of this information is actually stored in the advanced help; please
* check the API topic. This help will primarily be aimed at documenting
* classes and function calls.
*
* An online version of the advanced help API documentation is available from:
* @link http://views-help.doc.logrus.com/help/views/api @endlink
*
* Topics:
* - @ref view_lifetime
* - @ref views_hooks
* - @ref views_handlers
* - @ref views_plugins
* - @ref views_templates
*/
/**
* @page view_lifetime The life of a view
*
* This page explains the basic cycle of a view and what processes happen.
*/
/**
* @page views_handlers About Views' handlers
*
* This page explains what views handlers are, how they're written, and what
* the basic conventions are.
*
* - @ref views_field_handlers
* - @ref views_sort_handlers
* - @ref views_filter_handlers
* - @ref views_argument_handlers
* - @ref views_relationship_handlers
*/
/**
* @page views_plugins About Views' plugins
*
* This page explains what views plugins are, how they're written, and what
* the basic conventions are.
*
* - @ref views_display_plugins
* - @ref views_style_plugins
* - @ref views_row_plugins
*/
/**
* @defgroup views_hooks Views' hooks
* @{
* Hooks that can be implemented by other modules in order to implement the
* Views API.
*/
/**
* 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.
* @link http://views-help.doc.logrus.com/help/views/api-tables @endlink
*/
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)
// );
// 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. 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(
'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.
// This 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.
// 'left_field' is the primary key in the referenced table.
// 'field' is the foreign key in this table.
'node' => array(
'left_field' => 'nid',
'field' => 'nid',
),
);
// Next, describe each of the individual fields in this table to Views. For
// each field, you may define what field, sort, argument, and/or filter
// handlers it supports. This will determine where in the Views interface you
// may use the field.
// Node ID field.
$data['example_table']['nid'] = array(
'title' => t('Example content'),
'help' => t('Some example content that references a node.'),
// Because this is a foreign key to the {node} table. This allows us to
// have, when the view is configured with this relationship, all the fields
// for the related node available.
'relationship' => array(
'base' => 'node',
'field' => 'nid',
'handler' => 'views_handler_relationship',
'label' => t('Example node'),
),
);
// 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',
'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',
'label' => t('Published'),
'type' => 'yes-no',
// use boolean_field = 1 instead of boolean_field <> 0 in WHERE statment
'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;
}
/**
* Alter table structure.
*
* You can add/edit/remove to existing tables defined by hook_views_data().
*
* 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.
* @link http://views-help.doc.logrus.com/help/views/api-tables @endlink
*/
function hook_views_data_alter(&$data) {
// This example alters the title of the node: nid field for the admin.
$data['node']['nid']['title'] = t('Node-Nid');
// This example adds a example field to the users table
$data['users']['example_field'] = array(
'title' => t('Example field'),
'help' => t('Some examüple content that references a user'),
'handler' => 'hook_handlers_field_example_field',
);
// This example changes the handler of the node title field.
// In this handler you could do stuff, like preview of the node, when clicking the node title.
$data['node']['title']['handler'] = 'modulename_handlers_field_node_title';
}
/**
* 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:
* - style: 'even empty'
*/
function hook_views_plugins() {
// example code here
}
/**
* Alter existing plugins data, defined by modules.
*/
function hook_views_plugins_alter(&$plugins) {
// Add apachesolr to the base of the node row plugin.
$plugins['row']['node']['base'][] = 'apachesolr';
}
/**
* 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.
*/
function hook_views_handlers() {
// example code here
}
/**
* Register View API information. This is required for your module to have
* its include files loaded; for example, when implementing
* hook_views_default_views().
*
* @return
* 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.
* - template path: (optional) A path where the module has stored it's views template files.
* When you have specificed this key views automatically uses the template files for the views.
* You can use the same naming conventions like for normal views template files.
*/
function hook_views_api() {
return array(
'api' => 2,
'path' => drupal_get_path('module', 'example') . '/includes/views',
'template path' => drupal_get_path('module', 'example') . 'themes',
);
}
/**
* 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.
*
* The 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'.
*
* This hook requires an array of views, where each array has key/value pair and must
* have $value == $view->name, it is invalid if the keys not match.
*
* The $view->disabled boolean flag indicates whether the View should be
* enabled or disabled by default.
*
*
* @return
* 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.
*/
function hook_views_default_views() {
// Begin copy and paste of output from the Export tab of a view.
$view = new view();
$view->name = 'frontpage';
$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.');
$view->tag = t('default');
$view->base_table = 'node';
$view->api_version = 2;
$view->disabled = FALSE;
// Edit this to true to make a default view disabled initially
$view->display = array();
$display = new views_display();
$display->id = 'default';
$display->display_title = t('Defaults');
$display->display_plugin = 'default';
$display->position = '1';
$display->display_options = array(
'style_plugin' => 'default',
'style_options' => array(),
'row_plugin' => 'node',
'row_options' => array(
'teaser' => 1,
'links' => 1,
),
'relationships' => array(),
'fields' => array(),
'sorts' => array(
'sticky' => array(
'id' => 'sticky',
'table' => 'node',
'field' => 'sticky',
'order' => 'ASC',
),
'created' => array(
'id' => 'created',
'table' => 'node',
'field' => 'created',
'order' => 'ASC',
'relationship' => 'none',
'granularity' => 'second',
),
),
'arguments' => array(),
'filters' => array(
'promote' => array(
'id' => 'promote',
'table' => 'node',
'field' => 'promote',
'operator' => '=',
'value' => '1',
'group' => 0,
'exposed' => false,
'expose' => array(
'operator' => false,
'label' => '',
),
),
'status' => array(
'id' => 'status',
'table' => 'node',
'field' => 'status',
'operator' => '=',
'value' => '1',
'group' => 0,
'exposed' => false,
'expose' => array(
'operator' => false,
'label' => '',
),
),
),
'items_per_page' => 10,
'use_pager' => '1',
'pager_element' => 0,
'title' => '',
'header' => '',
'header_format' => '1',
'footer' => '',
'footer_format' => '1',
'empty' => '',
'empty_format' => '1',
);
$view->display['default'] = $display;
$display = new views_display();
$display->id = 'page';
$display->display_title = t('Page');
$display->display_plugin = 'page';
$display->position = '2';
$display->display_options = array(
'defaults' => array(
'access' => true,
'title' => true,
'header' => true,
'header_format' => true,
'header_empty' => true,
'footer' => true,
'footer_format' => true,
'footer_empty' => true,
'empty' => true,
'empty_format' => true,
'items_per_page' => true,
'offset' => true,
'use_pager' => true,
'pager_element' => true,
'link_display' => true,
'php_arg_code' => true,
'exposed_options' => true,
'style_plugin' => true,
'style_options' => true,
'row_plugin' => true,
'row_options' => true,
'relationships' => true,
'fields' => true,
'sorts' => true,
'arguments' => true,
'filters' => true,
'use_ajax' => true,
'distinct' => true,
),
'relationships' => array(),
'fields' => array(),
'sorts' => array(),
'arguments' => array(),
'filters' => array(),
'path' => 'frontpage',
);
$view->display['page'] = $display;
$display = new views_display();
$display->id = 'feed';
$display->display_title = t('Feed');
$display->display_plugin = 'feed';
$display->position = '3';
$display->display_options = array(
'defaults' => array(
'access' => true,
'title' => false,
'header' => true,
'header_format' => true,
'header_empty' => true,
'footer' => true,
'footer_format' => true,
'footer_empty' => true,
'empty' => true,
'empty_format' => true,
'use_ajax' => true,
'items_per_page' => true,
'offset' => true,
'use_pager' => true,
'pager_element' => true,
'use_more' => true,
'distinct' => true,
'link_display' => true,
'php_arg_code' => true,
'exposed_options' => true,
'style_plugin' => false,
'style_options' => false,
'row_plugin' => false,
'row_options' => false,
'relationships' => true,
'fields' => true,
'sorts' => true,
'arguments' => true,
'filters' => true,
),
'relationships' => array(),
'fields' => array(),
'sorts' => array(),
'arguments' => array(),
'filters' => array(),
'displays' => array(
'default' => 'default',
'page' => 'page',
),
'style_plugin' => 'rss',
'style_options' => array(
'mission_description' => 1,
'description' => '',
),
'row_plugin' => 'node_rss',
'row_options' => array(
'item_length' => 'default',
),
'path' => 'rss.xml',
'title' => t('Front page feed'),
);
$view->display['feed'] = $display;
// End copy and paste of Export tab output.
// Add view to list of views to provide.
$views[$view->name] = $view;
// ...Repeat all of the above for each view the module should provide.
// At the end, return array of default views.
return $views;
}
/**
* Alter default views defined by other modules.
*
* This hook is called right before all default views are cached to the
* database. It takes a keyed array of views by reference.
*
* Example usage to add a field to a view:
* @code
* $handler =& $view->display['DISPLAY_ID']->handler;
* // Add the user name field to the view.
* $handler->display->display_options['fields']['name']['id'] = 'name';
* $handler->display->display_options['fields']['name']['table'] = 'users';
* $handler->display->display_options['fields']['name']['field'] = 'name';
* $handler->display->display_options['fields']['name']['label'] = 'Author';
* $handler->display->display_options['fields']['name']['link_to_user'] = 1;
* @endcode
*/
function hook_views_default_views_alter(&$views) {
if (isset($views['taxonomy_term'])) {
$views['taxonomy_term']->display['default']->display_options['title'] = 'Categories';
}
}
/**
* 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'.
*/
function hook_views_convert() {
// example code here
}
/**
* Stub hook documentation
*/
function hook_views_query_substitutions() {
// example code here
}
/**
* This hook is called to get a list of placeholders and their substitutions,
* used when preprocessing a View with form elements.
*/
function hook_views_form_substitutions() {
return array(
'<!--views-form-example-substitutions-->' => 'Example Substitution',
);
}
/**
* Views form (View with form elements) validate handler.
* Called for all steps ($form_state['storage']['step']) of the multistep form.
*/
function hook_views_form_validate($form, &$form_state) {
// example code here
}
/**
* Views form (View with form elements) submit handler.
* Called for all steps ($form_state['storage']['step']) of the multistep form.
*/
function hook_views_form_submit($form, &$form_state) {
// example code here
}
/**
* This hook is called at the very beginning of views processing,
* before anything is done.
*
* Adding output to the view can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after.
*/
function hook_views_pre_view(&$view, &$display_id, &$args) {
// example code here
}
/**
* 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 can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after.
*/
function hook_views_pre_build(&$view) {
// example code here
}
/**
* This hook is called right after the build process. The query is
* now fully built, but it has not yet been run through db_rewrite_sql.
*
* Adding output to the view can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after.
*/
function hook_views_post_build(&$view) {
// example code here
}
/**
* 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 can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after.
*/
function hook_views_pre_execute(&$view) {
// example code here
}
/**
* This hook is called right after the execute process. The query has
* been executed, but the pre_render() phase has not yet happened for
* handlers.
*
* Adding output to the view can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after. Altering the
* content can be achieved by editing the items of $view->result.
*/
function hook_views_post_execute(&$view) {
// example code here
}
/**
* 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 can be accomplished by placing text on
* $view->attachment_before and $view->attachment_after. Altering the
* content can be achieved by editing the items of $view->result.
*
* This hook can be utilized by themes.
*/
function hook_views_pre_render(&$view) {
// example code here
}
/**
* 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:
*
* <!--post-FIELD-NID-->
*
* And then in the post render, create an array with the text that should
* go there:
*
* strtr($output, array('<!--post-FIELD-1-->', '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.
*/
function hook_views_post_render(&$view, &$output, &$cache) {
}
/**
* 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'.
*
*/
function hook_views_query_alter(&$view, &$query) {
// example code here
}
/**
* 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 theme_links
*/
function hook_views_admin_links_alter(&$links, $view) {
// example code here
}
/**
* 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 theme_table
*/
function hook_views_preview_info_alter(&$rows, $view) {
// example code here
}
/**
* @}
*/
Functions
Name | Description |
---|---|
hook_views_admin_links_alter | 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'. |
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(). |
hook_views_convert | Stub hook documentation |
hook_views_data | Describe table structure to Views. |
hook_views_data_alter | Alter table structure. |
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 | Alter default views defined by other modules. |
hook_views_form_submit | Views form (View with form elements) submit handler. Called for all steps ($form_state['storage']['step']) of the multistep form. |
hook_views_form_substitutions | This hook is called to get a list of placeholders and their substitutions, used when preprocessing a View with form elements. |
hook_views_form_validate | Views form (View with form elements) validate handler. Called for all steps ($form_state['storage']['step']) of the multistep form. |
hook_views_handlers | Register handler, file and parent information so that handlers can be loaded only on request. |
hook_views_plugins | The full documentation for this hook is now in the advanced help. |
hook_views_plugins_alter | Alter existing plugins data, defined by modules. |
hook_views_post_build | This hook is called right after the build process. The query is now fully built, but it has not yet been run through db_rewrite_sql. |
hook_views_post_execute | This hook is called right after the execute process. The query has been executed, but the pre_render() phase has not yet happened for handlers. |
hook_views_post_render | Post process any rendered data. |
hook_views_preview_info_alter | 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'. |
hook_views_pre_build | 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 | 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. |
hook_views_pre_render | 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. |
hook_views_pre_view | This hook is called at the very beginning of views processing, before anything is done. |
hook_views_query_alter | Stub hook documentation |
hook_views_query_substitutions | Stub hook documentation |