summaryrefslogtreecommitdiff
path: root/kolab.org/www/drupal-7.15/sites/all/modules/views/help/api-plugins.html
blob: 4d1c120d06b6d9865e6ccde2289735a522ff9149 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
In Views, a plugin is a bit like a handler, but plugins are not directly responsible for building the query. Instead, they are objects that are used to display the view or make other modifications.

There are 10 types of plugins in Views:
<dl>
<dt>Display</dt>
<dd>Display plugins are responsible for controlling <strong>where</strong> a view lives. Page and block are the most common displays, as well as the ubiquitous 'default' display which is likely what will be embedded.</dd>
<dt>Style</dt>
<dd>Style plugins control how a view is displayed. For the most part they are object wrappers around theme templates.
<dt>Row style</dt>
<dd>Row styles handle each individual record from a node.</dd>
<dt>Argument default</dt>
<dd>Argument default plugins allow pluggable ways of providing arguments for blocks. Views includes plugins to extract node and user IDs from the URL; additional plugins could be used for a wide variety of tasks.</dd>
<dt>Argument validator</dt>
<dd>Validator plugins can ensure arguments are valid, and even do transformations on the arguments.</dd>
<dt>Access</dt>
<dd>Access plugins are responsible for controlling access to the view.</dd>
<dt>Query</dt>
<dd>Query plugins generate and execute a query, it can be seen as a data backend. The default implementation
is using sql.</dd>
<dt>Cache</dt>
<dd>Cache plugins control the storage and loading of caches. Currently they can do both result and render caching,
but maybe one day cache the generated query</dd>
<dt>Pager plugins</dt>
<dd>Pager plugins take care of everything regarding pagers. From getting and setting the total amount of items
to render the pager and setting the global pager arrays.</dd>
<dt>Exposed form plugins</dt>
<dd>Exposed form plugins are responsible for building, rendering and controlling exposed forms. They can expose new
parts of the view to the user and more.</dd>
<dt>Localization plugins</dt>
<dd>Localization plugins take care how the view options are translated. There are example implementations
for t(), none translation and i18n.</dd>
</dl>

Plugins are registered by implementing <strong>hook_views_plugins()</strong> in your modulename.views.inc file and returning an array of data.
For examples please look at views_views_plugins() in views/includes/plugins.inc as it has examples
for all of them.

For example plugins please look at the one provided by views, too.

Similar to handlers take sure that you added the plugin file to the module.info.

The array will look something like this:
<pre>
  return array(
    'display' =&gt; array(
      // ... list of display plugins,
     ),
    'style' =&gt; array(
      // ... list of style plugins,
     ),
    'row' =&gt; array(
      // ... list of row style plugins,
     ),
    'argument default' =&gt; array(
      // ... list of argument default plugins,
     ),
    'argument validator' =&gt; array(
      // ... list of argument validator plugins,
     ),
     'access' =&gt; array(
      // ... list of access plugins,
     ),
     'query' =&gt; array(
       // ... list of query plugins,
      ),,
     'cache' =&gt; array(
       // ... list of cache plugins,
      ),,
     'pager' =&gt; array(
       // ... list of pager plugins,
      ),,
     'exposed_form' =&gt; array(
       // ... list of exposed_form plugins,
      ),,
     'localization' =&gt; array(
       // ... list of localization plugins,
      ),
  );
</pre>

Each plugin will be registered with an identifier for the plugin, plus a fairly lengthy list of items that can define how and where the plugin is used. Here is an example from Views core:

<pre>
      'node' =&gt; array(
        'title' =&gt; t('Node'),
        'help' =&gt; t('Display the node with standard node view.'),
        'handler' =&gt; 'views_plugin_row_node_view',
        'path' =&gt; drupal_get_path('module', 'views') . '/modules/node', // not necessary for most modules
        'theme' =&gt; 'views_view_row_node',
        'base' =&gt; array('node'), // only works with 'node' as base.
        'uses options' =&gt; TRUE,
        'type' =&gt; 'normal',
      ),
</pre>

Of particular interest is the <em>path</em> directive, which works a little differently from handler registration; each plugin must define its own path, rather than relying on a global info for the paths. For example:

<pre>
      'feed' =&gt; array(
        'title' =&gt; t('Feed'),
        'help' =&gt; t('Display the view as a feed, such as an RSS feed.'),
        'handler' =&gt; 'views_plugin_display_feed',
        'uses hook menu' =&gt; TRUE,
        'use ajax' =&gt; FALSE,
        'use pager' =&gt; FALSE,
        'accept attachments' =&gt; FALSE,
        'admin' =&gt; t('Feed'),
        'help topic' =&gt; 'display-feed',
      ),
</pre>

Please be sure to prefix your plugin identifiers with your module name to ensure namespace safety; after all, two different modules could try to implement the 'grid2' plugin, and that would cause one plugin to completely fail.

...TODO: Finish this document....