[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: docs.php,v 1.16.2.2 2010/03/08 20:04:40 merlinofchaos Exp $
   3  /**
   4   * @file
   5   * This file contains no working PHP code; it exists to provide additional documentation
   6   * for doxygen as well as to document hooks in the standard Drupal manner.
   7   */
   8  
   9  /**
  10   * @mainpage Views 2 API Manual
  11   *
  12   * Much of this information is actually stored in the advanced help; please
  13   * check the API topic. This help will primarily be aimed at documenting
  14   * classes and function calls.
  15   *
  16   * An online version of the advanced help API documentation is available from:
  17   * @link http://views-help.doc.logrus.com/help/views/api @endlink
  18   *
  19   * Topics:
  20   * - @ref view_lifetime
  21   * - @ref views_hooks
  22   * - @ref views_handlers
  23   * - @ref views_plugins
  24   * - @ref views_templates
  25   */
  26  
  27  /**
  28   * @page view_lifetime The life of a view
  29   *
  30   * This page explains the basic cycle of a view and what processes happen.
  31   */
  32  
  33  /**
  34   * @page views_handlers About Views' handlers
  35   *
  36   * This page explains what views handlers are, how they're written, and what
  37   * the basic conventions are.
  38   *
  39   * - @ref views_field_handlers
  40   * - @ref views_sort_handlers
  41   * - @ref views_filter_handlers
  42   * - @ref views_argument_handlers
  43   * - @ref views_relationship_handlers
  44   */
  45  
  46  /**
  47   * @page views_plugins About Views' plugins
  48   *
  49   * This page explains what views plugins are, how they're written, and what
  50   * the basic conventions are.
  51   *
  52   * - @ref views_display_plugins
  53   * - @ref views_style_plugins
  54   * - @ref views_row_plugins
  55   */
  56  
  57  /**
  58   * @defgroup views_hooks Views' hooks
  59   * @{
  60   * Hooks that can be implemented by other modules in order to implement the
  61   * Views API.
  62   */
  63  
  64  /**
  65   * Describe table structure to Views.
  66   *
  67   * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
  68   * This must either be in the same directory as the .module file or in a subdirectory
  69   * named 'includes'.
  70   *
  71   * The full documentation for this hook is in the advanced help.
  72   * @link http://views-help.doc.logrus.com/help/views/api-tables @endlink
  73   */
  74  function hook_views_data() {
  75    // This example describes how to write hook_views_data() for the following
  76    // table:
  77    //
  78    // CREATE TABLE example_table (
  79    //   nid INT(11) NOT NULL         COMMENT 'Primary key; refers to {node}.nid.',
  80    //   plain_text_field VARCHAR(32) COMMENT 'Just a plain text field.',
  81    //   numeric_field INT(11)        COMMENT 'Just a numeric field.',
  82    //   boolean_field INT(1)         COMMENT 'Just an on/off field.',
  83    //   timestamp_field INT(8)       COMMENT 'Just a timestamp field.',
  84    //   PRIMARY KEY(nid)
  85    // );
  86  
  87    // The 'group' index will be used as a prefix in the UI for any of this
  88    // table's fields, sort criteria, etc. so it's easy to tell where they came
  89    // from.
  90    $data['example_table']['table']['group'] = t('Example table');
  91  
  92    // Define this as a base table. In reality this is not very useful for
  93    // this table, as it isn't really a distinct object of its own, but
  94    // it makes a good example.
  95    $data['example_table']['table']['base'] = array(
  96      'field' => 'nid',
  97      'title' => t('Example table'),
  98      'help' => t("Example table contains example content and can be related to nodes."),
  99      'weight' => -10,
 100    );
 101  
 102    // This table references the {node} table.
 103    // This creates an 'implicit' relationship to the node table, so that when 'Node'
 104    // is the base table, the fields are automatically available.
 105    $data['example_table']['table']['join'] = array(
 106      // Index this array by the table name to which this table refers.
 107      // 'left_field' is the primary key in the referenced table.
 108      // 'field' is the foreign key in this table.
 109      'node' => array(
 110        'left_field' => 'nid',
 111        'field' => 'nid',
 112      ),
 113    );
 114  
 115    // Next, describe each of the individual fields in this table to Views. For
 116    // each field, you may define what field, sort, argument, and/or filter
 117    // handlers it supports. This will determine where in the Views interface you
 118    // may use the field.
 119  
 120    // Node ID field.
 121    $data['example_table']['nid'] = array(
 122      'title' => t('Example content'),
 123      'help' => t('Some example content that references a node.'),
 124      // Because this is a foreign key to the {node} table. This allows us to
 125      // have, when the view is configured with this relationship, all the fields
 126      // for the related node available.
 127      'relationship' => array(
 128        'base' => 'node',
 129        'field' => 'nid',
 130        'handler' => 'views_handler_relationship',
 131        'label' => t('Example node'),
 132      ),
 133    );
 134  
 135    // Example plain text field.
 136    $data['example_table']['plain_text_field'] = array(
 137      'title' => t('Plain text field'),
 138      'help' => t('Just a plain text field.'),
 139      'field' => array(
 140        'handler' => 'views_handler_field',
 141        'click sortable' => TRUE,
 142      ),
 143      'sort' => array(
 144        'handler' => 'views_handler_sort',
 145      ),
 146      'filter' => array(
 147        'handler' => 'views_handler_filter_string',
 148      ),
 149      'argument' => array(
 150        'handler' => 'views_handler_argument_string',
 151      ),
 152    );
 153  
 154    // Example numeric text field.
 155    $data['example_table']['numeric_field'] = array(
 156      'title' => t('Numeric field'),
 157      'help' => t('Just a numeric field.'),
 158      'field' => array(
 159        'handler' => 'views_handler_field_numeric',
 160        'click sortable' => TRUE,
 161       ),
 162      'filter' => array(
 163        'handler' => 'views_handler_filter_numeric',
 164      ),
 165      'sort' => array(
 166        'handler' => 'views_handler_sort',
 167      ),
 168    );
 169  
 170    // Example boolean field.
 171    $data['example_table']['boolean_field'] = array(
 172      'title' => t('Boolean field'),
 173      'help' => t('Just an on/off field.'),
 174      'field' => array(
 175        'handler' => 'views_handler_field_boolean',
 176        'click sortable' => TRUE,
 177      ),
 178      'filter' => array(
 179        'handler' => 'views_handler_filter_boolean_operator',
 180        'label' => t('Published'),
 181        'type' => 'yes-no',
 182      ),
 183      'sort' => array(
 184        'handler' => 'views_handler_sort',
 185      ),
 186    );
 187  
 188    // Example timestamp field.
 189    $data['example_table']['timestamp_field'] = array(
 190      'title' => t('Timestamp field'),
 191      'help' => t('Just a timestamp field.'),
 192      'field' => array(
 193        'handler' => 'views_handler_field_date',
 194        'click sortable' => TRUE,
 195      ),
 196      'sort' => array(
 197        'handler' => 'views_handler_sort_date',
 198      ),
 199      'filter' => array(
 200        'handler' => 'views_handler_filter_date',
 201      ),
 202    );
 203  
 204    return $data;
 205  }
 206  
 207  /**
 208   * The full documentation for this hook is now in the advanced help.
 209   *
 210   * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 211   * This must either be in the same directory as the .module file or in a subdirectory
 212   * named 'includes'.
 213   *
 214   * This is a stub list as a reminder that this needs to be doc'd and is not used
 215   * in views anywhere so might not be remembered when this is formally documented:
 216   * - style: 'even empty'
 217   */
 218  function hook_views_plugins() {
 219    // example code here
 220  }
 221  
 222  /**
 223   * Alter existing plugins data, defined by modules.
 224   */
 225  function hook_views_plugins_alter(&$plugins) {
 226    // Add apachesolr to the base of the node row plugin.
 227    $plugins['row']['node']['base'][] = 'apachesolr';
 228  }
 229  
 230  /**
 231   * Register handler, file and parent information so that handlers can be
 232   * loaded only on request.
 233   *
 234   * The full documentation for this hook is in the advanced help.
 235   */
 236  function hook_views_handlers() {
 237    // example code here
 238  }
 239  
 240  /**
 241   * Register View API information. This is required for your module to have
 242   * its include files loaded; for example, when implementing
 243   * hook_views_default_views().
 244   *
 245   * @return
 246   *   An array with the following possible keys:
 247   *   - api:  (required) The version of the Views API the module implements.
 248   *   - path: (optional) If includes are stored somewhere other than within
 249   *       the root module directory or a subdirectory called includes, specify
 250   *       its path here.
 251   */
 252  function hook_views_api() {
 253    return array(
 254      'api' => 2,
 255      'path' => drupal_get_path('module', 'example') . '/includes/views', 
 256    );
 257  }
 258  
 259  /**
 260   * This hook allows modules to provide their own views which can either be used
 261   * as-is or as a "starter" for users to build from.
 262   *
 263   * This hook should be placed in MODULENAME.views_default.inc and it will be
 264   * auto-loaded. This must either be in the same directory as the .module file
 265   * or in a subdirectory named 'includes'.
 266   *
 267   * The $view->disabled boolean flag indicates whether the View should be
 268   * enabled or disabled by default.
 269   *
 270   * @return
 271   *   An associative array containing the structures of views, as generated from
 272   *   the Export tab, keyed by the view name. A best practice is to go through
 273   *   and add t() to all title and label strings, with the exception of menu
 274   *   strings.
 275   */
 276  function hook_views_default_views() {
 277    // Begin copy and paste of output from the Export tab of a view.
 278    $view = new view;
 279    $view->name = 'frontpage';
 280    $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.');
 281    $view->tag = t('default');
 282    $view->view_php = '';
 283    $view->base_table = 'node';
 284    $view->is_cacheable = '0';
 285    $view->api_version = 2;
 286    $view->disabled = FALSE; // Edit this to true to make a default view disabled initially
 287    $view->display = array();
 288      $display = new views_display;
 289      $display->id = 'default';
 290      $display->display_title = t('Defaults');
 291      $display->display_plugin = 'default';
 292      $display->position = '1';
 293      $display->display_options = array (
 294      'style_plugin' => 'default',
 295      'style_options' =>
 296      array (
 297      ),
 298      'row_plugin' => 'node',
 299      'row_options' =>
 300      array (
 301        'teaser' => 1,
 302        'links' => 1,
 303      ),
 304      'relationships' =>
 305      array (
 306      ),
 307      'fields' =>
 308      array (
 309      ),
 310      'sorts' =>
 311      array (
 312        'sticky' =>
 313        array (
 314          'id' => 'sticky',
 315          'table' => 'node',
 316          'field' => 'sticky',
 317          'order' => 'ASC',
 318        ),
 319        'created' =>
 320        array (
 321          'id' => 'created',
 322          'table' => 'node',
 323          'field' => 'created',
 324          'order' => 'ASC',
 325          'relationship' => 'none',
 326          'granularity' => 'second',
 327        ),
 328      ),
 329      'arguments' =>
 330      array (
 331      ),
 332      'filters' =>
 333      array (
 334        'promote' =>
 335        array (
 336          'id' => 'promote',
 337          'table' => 'node',
 338          'field' => 'promote',
 339          'operator' => '=',
 340          'value' => '1',
 341          'group' => 0,
 342          'exposed' => false,
 343          'expose' =>
 344          array (
 345            'operator' => false,
 346            'label' => '',
 347          ),
 348        ),
 349        'status' =>
 350        array (
 351          'id' => 'status',
 352          'table' => 'node',
 353          'field' => 'status',
 354          'operator' => '=',
 355          'value' => '1',
 356          'group' => 0,
 357          'exposed' => false,
 358          'expose' =>
 359          array (
 360            'operator' => false,
 361            'label' => '',
 362          ),
 363        ),
 364      ),
 365      'items_per_page' => 10,
 366      'use_pager' => '1',
 367      'pager_element' => 0,
 368      'title' => '',
 369      'header' => '',
 370      'header_format' => '1',
 371      'footer' => '',
 372      'footer_format' => '1',
 373      'empty' => '',
 374      'empty_format' => '1',
 375    );
 376    $view->display['default'] = $display;
 377      $display = new views_display;
 378      $display->id = 'page';
 379      $display->display_title = t('Page');
 380      $display->display_plugin = 'page';
 381      $display->position = '2';
 382      $display->display_options = array (
 383      'defaults' =>
 384      array (
 385        'access' => true,
 386        'title' => true,
 387        'header' => true,
 388        'header_format' => true,
 389        'header_empty' => true,
 390        'footer' => true,
 391        'footer_format' => true,
 392        'footer_empty' => true,
 393        'empty' => true,
 394        'empty_format' => true,
 395        'items_per_page' => true,
 396        'offset' => true,
 397        'use_pager' => true,
 398        'pager_element' => true,
 399        'link_display' => true,
 400        'php_arg_code' => true,
 401        'exposed_options' => true,
 402        'style_plugin' => true,
 403        'style_options' => true,
 404        'row_plugin' => true,
 405        'row_options' => true,
 406        'relationships' => true,
 407        'fields' => true,
 408        'sorts' => true,
 409        'arguments' => true,
 410        'filters' => true,
 411        'use_ajax' => true,
 412        'distinct' => true,
 413      ),
 414      'relationships' =>
 415      array (
 416      ),
 417      'fields' =>
 418      array (
 419      ),
 420      'sorts' =>
 421      array (
 422      ),
 423      'arguments' =>
 424      array (
 425      ),
 426      'filters' =>
 427      array (
 428      ),
 429      'path' => 'frontpage',
 430    );
 431    $view->display['page'] = $display;
 432      $display = new views_display;
 433      $display->id = 'feed';
 434      $display->display_title = t('Feed');
 435      $display->display_plugin = 'feed';
 436      $display->position = '3';
 437      $display->display_options = array (
 438      'defaults' =>
 439      array (
 440        'access' => true,
 441        'title' => false,
 442        'header' => true,
 443        'header_format' => true,
 444        'header_empty' => true,
 445        'footer' => true,
 446        'footer_format' => true,
 447        'footer_empty' => true,
 448        'empty' => true,
 449        'empty_format' => true,
 450        'use_ajax' => true,
 451        'items_per_page' => true,
 452        'offset' => true,
 453        'use_pager' => true,
 454        'pager_element' => true,
 455        'use_more' => true,
 456        'distinct' => true,
 457        'link_display' => true,
 458        'php_arg_code' => true,
 459        'exposed_options' => true,
 460        'style_plugin' => false,
 461        'style_options' => false,
 462        'row_plugin' => false,
 463        'row_options' => false,
 464        'relationships' => true,
 465        'fields' => true,
 466        'sorts' => true,
 467        'arguments' => true,
 468        'filters' => true,
 469      ),
 470      'relationships' =>
 471      array (
 472      ),
 473      'fields' =>
 474      array (
 475      ),
 476      'sorts' =>
 477      array (
 478      ),
 479      'arguments' =>
 480      array (
 481      ),
 482      'filters' =>
 483      array (
 484      ),
 485      'displays' =>
 486      array (
 487        'default' => 'default',
 488        'page' => 'page',
 489      ),
 490      'style_plugin' => 'rss',
 491      'style_options' =>
 492      array (
 493        'mission_description' => 1,
 494        'description' => '',
 495      ),
 496      'row_plugin' => 'node_rss',
 497      'row_options' =>
 498      array (
 499        'item_length' => 'default',
 500      ),
 501      'path' => 'rss.xml',
 502      'title' => t('Front page feed'),
 503    );
 504    $view->display['feed'] = $display;
 505    // End copy and paste of Export tab output.
 506  
 507    // Add view to list of views to provide.
 508    $views[$view->name] = $view;
 509  
 510    // ...Repeat all of the above for each view the module should provide.
 511  
 512    // At the end, return array of default views.
 513    return $views;
 514  }
 515  
 516  /**
 517   * This hook is called right before all default views are cached to the
 518   * database. It takes a keyed array of views by reference.
 519   */
 520  function hook_views_default_views_alter(&$views) {
 521    if (isset($views['taxonomy_term'])) {
 522      $views['taxonomy_term']->set_display('default');
 523      $views['taxonomy_term']->display_handler->set_option('title', 'Categories');
 524    }
 525  }
 526  
 527  /**
 528   * Stub hook documentation
 529   *
 530   * This hook should be placed in MODULENAME.views_convert.inc and it will be auto-loaded.
 531   * This must either be in the same directory as the .module file or in a subdirectory
 532   * named 'includes'.
 533   */
 534  function hook_views_convert() {
 535    // example code here
 536  }
 537  
 538  /**
 539   * Stub hook documentation
 540   */
 541  function hook_views_query_substitutions() {
 542    // example code here
 543  }
 544  
 545  /**
 546   * This hook is called at the very beginning of views processing,
 547   * before anything is done.
 548   *
 549   * Adding output to the view can be accomplished by placing text on
 550   * $view->attachment_before and $view->attachment_after.
 551   */
 552  function hook_views_pre_view(&$view, &$display_id, &$args) {
 553    // example code here
 554  }
 555  
 556  /**
 557   * This hook is called right before the build process, but after displays
 558   * are attached and the display performs its pre_execute phase.
 559   *
 560   * Adding output to the view can be accomplished by placing text on
 561   * $view->attachment_before and $view->attachment_after.
 562   */
 563  function hook_views_pre_build(&$view) {
 564    // example code here
 565  }
 566  
 567  /**
 568   * This hook is called right before the execute process. The query is
 569   * now fully built, but it has not yet been run through db_rewrite_sql.
 570   *
 571   * Adding output to the view can be accomplished by placing text on
 572   * $view->attachment_before and $view->attachment_after.
 573   */
 574  function hook_views_pre_execute(&$view) {
 575    // example code here
 576  }
 577  
 578  /**
 579   * This hook is called right before the render process. The query has
 580   * been executed, and the pre_render() phase has already happened for
 581   * handlers, so all data should be available.
 582   *
 583   * Adding output to the view can be accomplished by placing text on
 584   * $view->attachment_before and $view->attachment_after. Altering the
 585   * content can be achieved by editing the items of $view->result.
 586   *
 587   * This hook can be utilized by themes.
 588   */
 589  function hook_views_pre_render(&$view) {
 590    // example code here
 591  }
 592  
 593  /**
 594   * Post process any rendered data.
 595   *
 596   * This can be valuable to be able to cache a view and still have some level of
 597   * dynamic output. In an ideal world, the actual output will include HTML
 598   * comment based tokens, and then the post process can replace those tokens.
 599   *
 600   * Example usage. If it is known that the view is a node view and that the
 601   * primary field will be a nid, you can do something like this:
 602   *
 603   * <!--post-FIELD-NID-->
 604   *
 605   * And then in the post render, create an array with the text that should
 606   * go there:
 607   *
 608   * strtr($output, array('<!--post-FIELD-1-->', 'output for FIELD of nid 1');
 609   *
 610   * All of the cached result data will be available in $view->result, as well,
 611   * so all ids used in the query should be discoverable.
 612   *
 613   * This hook can be utilized by themes.
 614   */
 615  function hook_views_post_render(&$view, &$output, &$cache) {
 616  
 617  }
 618  
 619  /**
 620   * Stub hook documentation
 621   *
 622   * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 623   * This must either be in the same directory as the .module file or in a subdirectory
 624   * named 'includes'.
 625   *
 626   */
 627  function hook_views_query_alter(&$view, &$query) {
 628    // example code here
 629  }
 630  
 631  /**
 632   * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 633   * This must either be in the same directory as the .module file or in a subdirectory
 634   * named 'includes'.
 635   *
 636   * Alter the links that appear over a view. They are in a format suitable for
 637   * theme('links').
 638   *
 639   * Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS
 640   * a reference in PHP5, and can be modified. Please be careful with it.
 641   *
 642   * @see theme_links
 643   */
 644  function hook_views_admin_links_alter(&$links, $view) {
 645    // example code here
 646  }
 647  
 648  /**
 649   * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 650   * This must either be in the same directory as the .module file or in a subdirectory
 651   * named 'includes'.
 652   *
 653   * Alter the rows that appear with a view, which includes path and query information.
 654   * The rows are suitable for theme('table').
 655   *
 656   * Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS
 657   * a reference in PHP5, and can be modified. Please be careful with it.
 658   *
 659   * @see theme_table
 660   */
 661  function hook_views_preview_info_alter(&$rows, $view) {
 662    // example code here
 663  }
 664  
 665  /**
 666   * @}
 667   */