[Summary view] [Print] [Text view]

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