← Back to branch summary

~spreadubuntu/spreadubuntu/devel-drupal6

« back to all changes in this revision

Viewing changes to sites/all/modules/views/docs/docs.php

  • Committer: ruben
  • Date: 2009-06-08 09:38:49 UTC
  • Revision ID: ruben@captive-20090608093849-s1qtsyctv2vwp1x1
SpreadUbuntu moving to Drupal6. Based on ubuntu-drupal theme and adding our modules

Show diffs side-by-side

added added

removed removed

Lines of Context:
sites/all/modules/views/docs/docs.php
 
1
<?php
 
2
// $Id: docs.php,v 1.13 2009/02/06 21:56:36 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
 * Register handler, file and parent information so that handlers can be
 
224
 * loaded only on request.
 
225
 *
 
226
 * The full documentation for this hook is in the advanced help.
 
227
 */
 
228
function hook_views_handlers() {
 
229
  // example code here
 
230
}
 
231
 
 
232
/**
 
233
 * Register View API information. This is required for your module to have
 
234
 * its include files loaded.
 
235
 *
 
236
 * The full documentation for this hook is in the advanced help.
 
237
 */
 
238
function hook_views_api() {
 
239
}
 
240
 
 
241
/**
 
242
 * This hook allows modules to provide their own views which can either be used
 
243
 * as-is or as a "starter" for users to build from.
 
244
 *
 
245
 * This hook should be placed in MODULENAME.views_default.inc and it will be
 
246
 * auto-loaded. This must either be in the same directory as the .module file
 
247
 * or in a subdirectory named 'includes'.
 
248
 *
 
249
 * The $view->disabled boolean flag indicates whether the View should be
 
250
 * enabled or disabled by default.
 
251
 *
 
252
 * @return
 
253
 *   An associative array containing the structures of views, as generated from
 
254
 *   the Export tab, keyed by the view name. A best practice is to go through
 
255
 *   and add t() to all title and label strings, with the exception of menu
 
256
 *   strings.
 
257
 */
 
258
function hook_views_default_views() {
 
259
  // Begin copy and paste of output from the Export tab of a view.
 
260
  $view = new view;
 
261
  $view->name = 'frontpage';
 
262
  $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.');
 
263
  $view->tag = t('default');
 
264
  $view->view_php = '';
 
265
  $view->base_table = 'node';
 
266
  $view->is_cacheable = '0';
 
267
  $view->api_version = 2;
 
268
  $view->disabled = FALSE; // Edit this to true to make a default view disabled initially
 
269
  $view->display = array();
 
270
    $display = new views_display;
 
271
    $display->id = 'default';
 
272
    $display->display_title = t('Defaults');
 
273
    $display->display_plugin = 'default';
 
274
    $display->position = '1';
 
275
    $display->display_options = array (
 
276
    'style_plugin' => 'default',
 
277
    'style_options' =>
 
278
    array (
 
279
    ),
 
280
    'row_plugin' => 'node',
 
281
    'row_options' =>
 
282
    array (
 
283
      'teaser' => 1,
 
284
      'links' => 1,
 
285
    ),
 
286
    'relationships' =>
 
287
    array (
 
288
    ),
 
289
    'fields' =>
 
290
    array (
 
291
    ),
 
292
    'sorts' =>
 
293
    array (
 
294
      'sticky' =>
 
295
      array (
 
296
        'id' => 'sticky',
 
297
        'table' => 'node',
 
298
        'field' => 'sticky',
 
299
        'order' => 'ASC',
 
300
      ),
 
301
      'created' =>
 
302
      array (
 
303
        'id' => 'created',
 
304
        'table' => 'node',
 
305
        'field' => 'created',
 
306
        'order' => 'ASC',
 
307
        'relationship' => 'none',
 
308
        'granularity' => 'second',
 
309
      ),
 
310
    ),
 
311
    'arguments' =>
 
312
    array (
 
313
    ),
 
314
    'filters' =>
 
315
    array (
 
316
      'promote' =>
 
317
      array (
 
318
        'id' => 'promote',
 
319
        'table' => 'node',
 
320
        'field' => 'promote',
 
321
        'operator' => '=',
 
322
        'value' => '1',
 
323
        'group' => 0,
 
324
        'exposed' => false,
 
325
        'expose' =>
 
326
        array (
 
327
          'operator' => false,
 
328
          'label' => '',
 
329
        ),
 
330
      ),
 
331
      'status' =>
 
332
      array (
 
333
        'id' => 'status',
 
334
        'table' => 'node',
 
335
        'field' => 'status',
 
336
        'operator' => '=',
 
337
        'value' => '1',
 
338
        'group' => 0,
 
339
        'exposed' => false,
 
340
        'expose' =>
 
341
        array (
 
342
          'operator' => false,
 
343
          'label' => '',
 
344
        ),
 
345
      ),
 
346
    ),
 
347
    'items_per_page' => 10,
 
348
    'use_pager' => '1',
 
349
    'pager_element' => 0,
 
350
    'title' => '',
 
351
    'header' => '',
 
352
    'header_format' => '1',
 
353
    'footer' => '',
 
354
    'footer_format' => '1',
 
355
    'empty' => '',
 
356
    'empty_format' => '1',
 
357
  );
 
358
  $view->display['default'] = $display;
 
359
    $display = new views_display;
 
360
    $display->id = 'page';
 
361
    $display->display_title = t('Page');
 
362
    $display->display_plugin = 'page';
 
363
    $display->position = '2';
 
364
    $display->display_options = array (
 
365
    'defaults' =>
 
366
    array (
 
367
      'access' => true,
 
368
      'title' => true,
 
369
      'header' => true,
 
370
      'header_format' => true,
 
371
      'header_empty' => true,
 
372
      'footer' => true,
 
373
      'footer_format' => true,
 
374
      'footer_empty' => true,
 
375
      'empty' => true,
 
376
      'empty_format' => true,
 
377
      'items_per_page' => true,
 
378
      'offset' => true,
 
379
      'use_pager' => true,
 
380
      'pager_element' => true,
 
381
      'link_display' => true,
 
382
      'php_arg_code' => true,
 
383
      'exposed_options' => true,
 
384
      'style_plugin' => true,
 
385
      'style_options' => true,
 
386
      'row_plugin' => true,
 
387
      'row_options' => true,
 
388
      'relationships' => true,
 
389
      'fields' => true,
 
390
      'sorts' => true,
 
391
      'arguments' => true,
 
392
      'filters' => true,
 
393
      'use_ajax' => true,
 
394
      'distinct' => true,
 
395
    ),
 
396
    'relationships' =>
 
397
    array (
 
398
    ),
 
399
    'fields' =>
 
400
    array (
 
401
    ),
 
402
    'sorts' =>
 
403
    array (
 
404
    ),
 
405
    'arguments' =>
 
406
    array (
 
407
    ),
 
408
    'filters' =>
 
409
    array (
 
410
    ),
 
411
    'path' => 'frontpage',
 
412
  );
 
413
  $view->display['page'] = $display;
 
414
    $display = new views_display;
 
415
    $display->id = 'feed';
 
416
    $display->display_title = t('Feed');
 
417
    $display->display_plugin = 'feed';
 
418
    $display->position = '3';
 
419
    $display->display_options = array (
 
420
    'defaults' =>
 
421
    array (
 
422
      'access' => true,
 
423
      'title' => false,
 
424
      'header' => true,
 
425
      'header_format' => true,
 
426
      'header_empty' => true,
 
427
      'footer' => true,
 
428
      'footer_format' => true,
 
429
      'footer_empty' => true,
 
430
      'empty' => true,
 
431
      'empty_format' => true,
 
432
      'use_ajax' => true,
 
433
      'items_per_page' => true,
 
434
      'offset' => true,
 
435
      'use_pager' => true,
 
436
      'pager_element' => true,
 
437
      'use_more' => true,
 
438
      'distinct' => true,
 
439
      'link_display' => true,
 
440
      'php_arg_code' => true,
 
441
      'exposed_options' => true,
 
442
      'style_plugin' => false,
 
443
      'style_options' => false,
 
444
      'row_plugin' => false,
 
445
      'row_options' => false,
 
446
      'relationships' => true,
 
447
      'fields' => true,
 
448
      'sorts' => true,
 
449
      'arguments' => true,
 
450
      'filters' => true,
 
451
    ),
 
452
    'relationships' =>
 
453
    array (
 
454
    ),
 
455
    'fields' =>
 
456
    array (
 
457
    ),
 
458
    'sorts' =>
 
459
    array (
 
460
    ),
 
461
    'arguments' =>
 
462
    array (
 
463
    ),
 
464
    'filters' =>
 
465
    array (
 
466
    ),
 
467
    'displays' =>
 
468
    array (
 
469
      'default' => 'default',
 
470
      'page' => 'page',
 
471
    ),
 
472
    'style_plugin' => 'rss',
 
473
    'style_options' =>
 
474
    array (
 
475
      'mission_description' => 1,
 
476
      'description' => '',
 
477
    ),
 
478
    'row_plugin' => 'node_rss',
 
479
    'row_options' =>
 
480
    array (
 
481
      'item_length' => 'default',
 
482
    ),
 
483
    'path' => 'rss.xml',
 
484
    'title' => t('Front page feed'),
 
485
  );
 
486
  $view->display['feed'] = $display;
 
487
  // End copy and paste of Export tab output.
 
488
 
 
489
  // Add view to list of views to provide.
 
490
  $views[$view->name] = $view;
 
491
 
 
492
  // ...Repeat all of the above for each view the module should provide.
 
493
 
 
494
  // At the end, return array of default views.
 
495
  return $views;
 
496
}
 
497
 
 
498
/**
 
499
 * Stub hook documentation
 
500
 *
 
501
 * This hook should be placed in MODULENAME.views_convert.inc and it will be auto-loaded.
 
502
 * This must either be in the same directory as the .module file or in a subdirectory
 
503
 * named 'includes'.
 
504
 */
 
505
function hook_views_convert() {
 
506
  // example code here
 
507
}
 
508
 
 
509
/**
 
510
 * Stub hook documentation
 
511
 */
 
512
function hook_views_query_substitutions() {
 
513
  // example code here
 
514
}
 
515
 
 
516
/**
 
517
 * This hook is called at the very beginning of views processing,
 
518
 * before anything is done.
 
519
 *
 
520
 * Adding output to the view cam be accomplished by placing text on
 
521
 * $view->attachment_before and $view->attachment_after
 
522
 */
 
523
function hook_views_pre_view(&$view, &$display_id, &$args) {
 
524
  // example code here
 
525
}
 
526
 
 
527
/**
 
528
 * This hook is called right before the build process, but after displays
 
529
 * are attached and the display performs its pre_execute phase.
 
530
 *
 
531
 * Adding output to the view cam be accomplished by placing text on
 
532
 * $view->attachment_before and $view->attachment_after
 
533
 */
 
534
function hook_views_pre_build(&$view) {
 
535
  // example code here
 
536
}
 
537
 
 
538
/**
 
539
 * This hook is called right before the execute process. The query is
 
540
 * now fully built, but it has not yet been run through db_rewrite_sql.
 
541
 *
 
542
 * Adding output to the view cam be accomplished by placing text on
 
543
 * $view->attachment_before and $view->attachment_after
 
544
 */
 
545
function hook_views_pre_execute(&$view) {
 
546
  // example code here
 
547
}
 
548
 
 
549
/**
 
550
 * This hook is called right before the render process. The query has
 
551
 * been executed, and the pre_render() phase has already happened for
 
552
 * handlers, so all data should be available.
 
553
 *
 
554
 * Adding output to the view cam be accomplished by placing text on
 
555
 * $view->attachment_before and $view->attachment_after
 
556
 */
 
557
function hook_views_pre_render(&$view) {
 
558
  // example code here
 
559
}
 
560
 
 
561
/**
 
562
 * Stub hook documentation
 
563
 *
 
564
 * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 
565
 * This must either be in the same directory as the .module file or in a subdirectory
 
566
 * named 'includes'.
 
567
 *
 
568
 */
 
569
function hook_views_query_alter(&$view, &$query) {
 
570
  // example code here
 
571
}
 
572
 
 
573
/**
 
574
 * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 
575
 * This must either be in the same directory as the .module file or in a subdirectory
 
576
 * named 'includes'.
 
577
 *
 
578
 * Alter the links that appear over a view. They are in a format suitable for
 
579
 * theme('links').
 
580
 *
 
581
 * Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS
 
582
 * a reference in PHP5, and can be modified. Please be careful with it.
 
583
 *
 
584
 * @see theme_links
 
585
 */
 
586
function hook_views_admin_links_alter(&$links, $view) {
 
587
  // example code here
 
588
}
 
589
 
 
590
/**
 
591
 * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
 
592
 * This must either be in the same directory as the .module file or in a subdirectory
 
593
 * named 'includes'.
 
594
 *
 
595
 * Alter the rows that appear with a view, which includes path and query information.
 
596
 * The rows are suitable for theme('table').
 
597
 *
 
598
 * Warning: $view is not a reference in PHP4 and cannot be modified here. But it IS
 
599
 * a reference in PHP5, and can be modified. Please be careful with it.
 
600
 *
 
601
 * @see theme_table
 
602
 */
 
603
function hook_views_preview_info_alter(&$rows, $view) {
 
604
  // example code here
 
605
}
 
606
 
 
607
/**
 
608
 * @}
 
609
 */