root / drupal7 / sites / all / modules / views / views.api.php @ 4003efde
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Describe hooks provided by the Views module.
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* @mainpage Views 3 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 |
* Topics:
|
16 |
* - @link views_lifetime The life of a view @endlink
|
17 |
* - @link views_hooks Views hooks @endlink
|
18 |
* - @link views_handlers About Views handlers @endlink
|
19 |
* - @link views_plugins About Views plugins @endlink
|
20 |
* - @link views_templates Views template files @endlink
|
21 |
* - @link views_module_handlers Views module handlers @endlink
|
22 |
*/
|
23 |
|
24 |
/**
|
25 |
* @defgroup views_lifetime The life of a view
|
26 |
* @{
|
27 |
* This page explains the basic cycle of a view and what processes happen.
|
28 |
*
|
29 |
* @todo.
|
30 |
* @}
|
31 |
*/
|
32 |
|
33 |
/**
|
34 |
* @defgroup views_handlers About Views handlers
|
35 |
* @{
|
36 |
* In Views, a handler is an object that is part of the view and is part of the
|
37 |
* query building flow.
|
38 |
*
|
39 |
* Handlers are objects; much of the time, the base handlers will work, but
|
40 |
* often you'll need to override the handler to achieve something meaningful.
|
41 |
* One typical handler override will be views_handler_filter_operator_in which
|
42 |
* allows you to have a filter select from a list of options; you'll need to
|
43 |
* override this to provide your list.
|
44 |
*
|
45 |
* Handlers have two distinct code flows; the UI flow and the view building
|
46 |
* flow.
|
47 |
*
|
48 |
* For the query flow:
|
49 |
* - handler->construct()
|
50 |
* - Create the initial handler; at this time it is not yet attached to a
|
51 |
* view. It is here that you can set basic defaults if needed, but there
|
52 |
* will be no knowledge of the environment yet.
|
53 |
* - handler->set_definition()
|
54 |
* - Set the data from hook_views_data() relevant to the handler.
|
55 |
* - handler->init()
|
56 |
* - Attach the handler to a view, and usually provides the options from the
|
57 |
* display.
|
58 |
* - handler->pre_query()
|
59 |
* - Run prior to the query() stage to do early processing.
|
60 |
* - handler->query()
|
61 |
* - Do the bulk of the work this handler needs to do to add itself to the
|
62 |
* query.
|
63 |
*
|
64 |
* Fields, being the only handlers concerned with output, also have an extended
|
65 |
* piece of the flow:
|
66 |
*
|
67 |
* - handler->pre_render(&$values)
|
68 |
* - Called prior to the actual rendering, this allows handlers to query for
|
69 |
* extra data; the entire resultset is available here, and this is where
|
70 |
* items that have "multiple values" per record can do their extra query for
|
71 |
* all of the records available. There are several examples of this at work
|
72 |
* in the code, see for example views_handler_field_user_roles.
|
73 |
* - handler->render()
|
74 |
* - This does the actual work of rendering the field.
|
75 |
*
|
76 |
* Most handlers are just extensions of existing classes with a few tweaks that
|
77 |
* are specific to the field in question. For example,
|
78 |
* views_handler_filter_in_operator provides a simple mechanism to set a
|
79 |
* multiple-value list for setting filter values. Below,
|
80 |
* views_handler_filter_node_type overrides the list options, but inherits
|
81 |
* everything else.
|
82 |
*
|
83 |
* @code
|
84 |
* class views_handler_filter_node_type extends views_handler_filter_in_operator {
|
85 |
* function get_value_options() {
|
86 |
* if (!isset($this->value_options)) {
|
87 |
* $this->value_title = t('Node type');
|
88 |
* $types = node_get_types();
|
89 |
* foreach ($types as $type => $info) {
|
90 |
* $options[$type] = $info->name;
|
91 |
* }
|
92 |
* $this->value_options = $options;
|
93 |
* }
|
94 |
* }
|
95 |
* }
|
96 |
* @endcode
|
97 |
*
|
98 |
* Handlers are stored in their own files and loaded on demand. Like all other
|
99 |
* module files, they must first be registered through the module's info file.
|
100 |
* For example:
|
101 |
*
|
102 |
* @code
|
103 |
* name = Example module
|
104 |
* description = "Gives an example of a module."
|
105 |
* core = 7.x
|
106 |
* files[] = example.module
|
107 |
* files[] = example.install
|
108 |
*
|
109 |
* ; Views handlers
|
110 |
* files[] = includes/views/handlers/example_handler_argument_string.inc
|
111 |
* @endcode
|
112 |
*
|
113 |
* The best place to learn more about handlers and how they work is to explore
|
114 |
* @link views_handlers Views' handlers @endlink and use existing handlers as a
|
115 |
* guide and a model. Understanding how views_handler and its child classes work
|
116 |
* is handy but you can do a lot just following these models. You can also
|
117 |
* explore the views module directory, particularly node.views.inc.
|
118 |
*
|
119 |
* Please note that while all handler names in views are prefixed with views_,
|
120 |
* you should use your own module's name to prefix your handler names in order
|
121 |
* to ensure namespace safety. Note that the basic pattern for handler naming
|
122 |
* goes like this:
|
123 |
*
|
124 |
* [module]_handler_[type]_[tablename]_[fieldname].
|
125 |
*
|
126 |
* Sometimes table and fieldname are not appropriate, but something that
|
127 |
* resembles what the table/field would be can be used.
|
128 |
*
|
129 |
* See also:
|
130 |
* - @link views_field_handlers Views field handlers @endlink
|
131 |
* - @link views_sort_handlers Views sort handlers @endlink
|
132 |
* - @link views_filter_handlers Views filter handlers @endlink
|
133 |
* - @link views_argument_handlers Views argument handlers @endlink
|
134 |
* - @link views_relationship_handlers Views relationship handlers @endlink
|
135 |
* - @link views_area_handlers Views area handlers @endlink
|
136 |
* @}
|
137 |
*/
|
138 |
|
139 |
/**
|
140 |
* @defgroup views_plugins About Views plugins
|
141 |
*
|
142 |
* In Views, a plugin is a bit like a handler, but plugins are not directly
|
143 |
* responsible for building the query. Instead, they are objects that are used
|
144 |
* to display the view or make other modifications.
|
145 |
*
|
146 |
* There are several types of plugins in Views:
|
147 |
* - Display: Display plugins are responsible for controlling *where* a view
|
148 |
* lives; that is, how they are being exposed to other parts of Drupal. Page
|
149 |
* and block are the most common displays, as well as the ubiquitous 'master'
|
150 |
* (or 'default') display.
|
151 |
* - Style: Style plugins control how a view is displayed. For the most part
|
152 |
* they are object wrappers around theme templates. Styles could for example
|
153 |
* be HTML lists or tables.
|
154 |
* - Row style: Row styles handle each individual record from the main view
|
155 |
* table. The two included by default render the entire entity (nodes only),
|
156 |
* or selected fields.
|
157 |
* - Argument default: Argument default plugins allow pluggable ways of
|
158 |
* providing default values for contextual filters (previously 'arguments').
|
159 |
* This is useful for blocks and other display types lacking a natural
|
160 |
* argument input. Examples are plugins to extract node and user IDs from the
|
161 |
* URL.
|
162 |
* - Argument validator: Validator plugins can ensure arguments are valid, and
|
163 |
* even do transformations on the arguments. They can also provide replacement
|
164 |
* patterns for the view title. For example, the 'content' validator
|
165 |
* verifies verifies that the argument value corresponds to a node, loads
|
166 |
* that node and provides the node title as a replacement pattern.
|
167 |
* - Access: Access plugins are responsible for controlling access to the view.
|
168 |
* Views includes plugins for checking user roles and individual permissions.
|
169 |
* - Query: Query plugins generate and execute a query, so they can be seen as
|
170 |
* a data backend. The default implementation is using SQL. There are
|
171 |
* contributed modules reading data from other sources, see for example the
|
172 |
* Views XML Backend module.
|
173 |
* - Cache: Cache plugins control the storage and loading of caches. Currently
|
174 |
* they can do both result and render caching, but maybe one day cache the
|
175 |
* generated query.
|
176 |
* - Pager plugins: Pager plugins take care of everything regarding pagers.
|
177 |
* From getting and setting the total amount of items to render the pager and
|
178 |
* setting the global pager arrays.
|
179 |
* - Exposed form plugins: Exposed form plugins are responsible for building,
|
180 |
* rendering and controlling exposed forms. They can expose new parts of the
|
181 |
* view to the user and more.
|
182 |
* - Localization plugins: Localization plugins take care how the view options
|
183 |
* are translated. There are example implementations for t(), 'no
|
184 |
* translation' and i18n.
|
185 |
* - Display extenders: Display extender plugins allow scaling of views options
|
186 |
* horizontally. This means that you can add options and do stuff on all
|
187 |
* views displays. One theoretical example is metatags for views.
|
188 |
*
|
189 |
* Plugins are registered by implementing hook_views_plugins() in your
|
190 |
* modulename.views.inc file and returning an array of data.
|
191 |
* For examples please look at views_views_plugins() in
|
192 |
* views/includes/plugins.inc as it has examples for all of them.
|
193 |
*
|
194 |
* Similar to handlers, make sure that you add your plugin files to the
|
195 |
* module.info file.
|
196 |
*
|
197 |
* The array defining plugins will look something like this:
|
198 |
* @code
|
199 |
* return array(
|
200 |
* 'display' => array(
|
201 |
* // ... list of display plugins,
|
202 |
* ),
|
203 |
* 'style' => array(
|
204 |
* // ... list of style plugins,
|
205 |
* ),
|
206 |
* 'row' => array(
|
207 |
* // ... list of row style plugins,
|
208 |
* ),
|
209 |
* 'argument default' => array(
|
210 |
* // ... list of argument default plugins,
|
211 |
* ),
|
212 |
* 'argument validator' => array(
|
213 |
* // ... list of argument validator plugins,
|
214 |
* ),
|
215 |
* 'access' => array(
|
216 |
* // ... list of access plugins,
|
217 |
* ),
|
218 |
* 'query' => array(
|
219 |
* // ... list of query plugins,
|
220 |
* ),,
|
221 |
* 'cache' => array(
|
222 |
* // ... list of cache plugins,
|
223 |
* ),,
|
224 |
* 'pager' => array(
|
225 |
* // ... list of pager plugins,
|
226 |
* ),,
|
227 |
* 'exposed_form' => array(
|
228 |
* // ... list of exposed_form plugins,
|
229 |
* ),,
|
230 |
* 'localization' => array(
|
231 |
* // ... list of localization plugins,
|
232 |
* ),
|
233 |
* 'display_extender' => array(
|
234 |
* // ... list of display extender plugins,
|
235 |
* ),
|
236 |
* );
|
237 |
* @endcode
|
238 |
*
|
239 |
* Each plugin will be registered with an identifier for the plugin, plus a
|
240 |
* fairly lengthy list of items that can define how and where the plugin is
|
241 |
* used. Here is an example of a row style plugin from Views core:
|
242 |
* @code
|
243 |
* 'node' => array(
|
244 |
* 'title' => t('Node'),
|
245 |
* 'help' => t('Display the node with standard node view.'),
|
246 |
* 'handler' => 'views_plugin_row_node_view',
|
247 |
* // Not necessary for most modules.
|
248 |
* 'path' => drupal_get_path('module', 'views') . '/modules/node',
|
249 |
* 'theme' => 'views_view_row_node',
|
250 |
* // Only works with 'node' as base.
|
251 |
* 'base' => array('node'),
|
252 |
* 'uses options' => TRUE,
|
253 |
* 'type' => 'normal',
|
254 |
* ),
|
255 |
* @endcode
|
256 |
*
|
257 |
* Of particular interest is the *path* directive, which works a little
|
258 |
* differently from handler registration; each plugin must define its own path,
|
259 |
* rather than relying on a global info for the paths. For example:
|
260 |
* @code
|
261 |
* 'feed' => array(
|
262 |
* 'title' => t('Feed'),
|
263 |
* 'help' => t('Display the view as a feed, such as an RSS feed.'),
|
264 |
* 'handler' => 'views_plugin_display_feed',
|
265 |
* 'uses hook menu' => TRUE,
|
266 |
* 'use ajax' => FALSE,
|
267 |
* 'use pager' => FALSE,
|
268 |
* 'accept attachments' => FALSE,
|
269 |
* 'admin' => t('Feed'),
|
270 |
* 'help topic' => 'display-feed',
|
271 |
* ),
|
272 |
* @endcode
|
273 |
*
|
274 |
* Please be sure to prefix your plugin identifiers with your module name to
|
275 |
* ensure namespace safety; after all, two different modules could try to
|
276 |
* implement the 'grid2' plugin, and that would cause one plugin to completely
|
277 |
* fail.
|
278 |
*
|
279 |
* @todo Finish this document.
|
280 |
*
|
281 |
* See also:
|
282 |
* - @link views_display_plugins Views display plugins @endlink
|
283 |
* - @link views_style_plugins Views style plugins @endlink
|
284 |
* - @link views_row_plugins Views row plugins @endlink
|
285 |
*/
|
286 |
|
287 |
/**
|
288 |
* @defgroup views_hooks Views hooks
|
289 |
* @{
|
290 |
* Hooks that can be implemented by other modules in order to implement the
|
291 |
* Views API.
|
292 |
*/
|
293 |
|
294 |
/**
|
295 |
* Describes data tables (or the equivalent) to Views.
|
296 |
*
|
297 |
* This hook should be placed in MODULENAME.views.inc and it will be auto
|
298 |
* loaded. MODULENAME.views.inc must be in the directory specified by the 'path'
|
299 |
* key returned by MODULENAME_views_api(), or the same directory as the .module
|
300 |
* file, if 'path' is unspecified.
|
301 |
*
|
302 |
* @return array
|
303 |
* An associative array describing the data structure. Primary key is the
|
304 |
* name used internally by Views for the table(s) – usually the actual table
|
305 |
* name. The values for the key entries are described in detail below.
|
306 |
*/
|
307 |
function hook_views_data() { |
308 |
// This example describes how to write hook_views_data() for the following
|
309 |
// table:
|
310 |
//
|
311 |
// CREATE TABLE example_table (
|
312 |
// nid INT(11) NOT NULL COMMENT 'Primary key; refers to {node}.nid.',
|
313 |
// plain_text_field VARCHAR(32) COMMENT 'Just a plain text field.',
|
314 |
// numeric_field INT(11) COMMENT 'Just a numeric field.',
|
315 |
// boolean_field INT(1) COMMENT 'Just an on/off field.',
|
316 |
// timestamp_field INT(8) COMMENT 'Just a timestamp field.',
|
317 |
// PRIMARY KEY(nid)
|
318 |
// );
|
319 |
// First, the entry $data['example_table']['table'] describes properties of
|
320 |
// the actual table – not its content.
|
321 |
// The 'group' index will be used as a prefix in the UI for any of this
|
322 |
// table's fields, sort criteria, etc. so it's easy to tell where they came
|
323 |
// from.
|
324 |
$data['example_table']['table']['group'] = t('Example table'); |
325 |
|
326 |
// Define this as a base table – a table that can be described in itself by
|
327 |
// views (and not just being brought in as a relationship). In reality this
|
328 |
// is not very useful for this table, as it isn't really a distinct object of
|
329 |
// its own, but it makes a good example.
|
330 |
$data['example_table']['table']['base'] = array( |
331 |
// This is the identifier field for the view.
|
332 |
'field' => 'nid', |
333 |
'title' => t('Example table'), |
334 |
'help' => t('Example table contains example content and can be related to nodes.'), |
335 |
'weight' => -10, |
336 |
); |
337 |
|
338 |
// This table references the {node} table. The declaration below creates an
|
339 |
// 'implicit' relationship to the node table, so that when 'node' is the base
|
340 |
// table, the fields are automatically available.
|
341 |
$data['example_table']['table']['join'] = array( |
342 |
// Index this array by the table name to which this table refers.
|
343 |
'node' => array( |
344 |
// The primary key in the referenced table.
|
345 |
'left_field' => 'nid', |
346 |
// The foreign key in this table.
|
347 |
'field' => 'nid', |
348 |
), |
349 |
); |
350 |
|
351 |
// Next, describe each of the individual fields in this table to Views. This
|
352 |
// is done by describing $data['example_table']['FIELD_NAME']. This part of
|
353 |
// the array may then have further entries:
|
354 |
// - title: The label for the table field, as presented in Views.
|
355 |
// - help: The description text for the table field.
|
356 |
// - relationship: A description of any relationship handler for the table
|
357 |
// field.
|
358 |
// - field: A description of any field handler for the table field.
|
359 |
// - sort: A description of any sort handler for the table field.
|
360 |
// - filter: A description of any filter handler for the table field.
|
361 |
// - argument: A description of any argument handler for the table field.
|
362 |
// - area: A description of any handler for adding content to header,
|
363 |
// footer or as no result behaviour.
|
364 |
//
|
365 |
// The handler descriptions are described with examples below.
|
366 |
// Node ID table field.
|
367 |
$data['example_table']['nid'] = array( |
368 |
'title' => t('Example content'), |
369 |
'help' => t('Some example content that references a node.'), |
370 |
// Define a relationship to the {node} table, so example_table views can
|
371 |
// add a relationship to nodes. If you want to define a relationship the
|
372 |
// other direction, use hook_views_data_alter(), or use the 'implicit' join
|
373 |
// method described above.
|
374 |
'relationship' => array( |
375 |
// The name of the table to join with.
|
376 |
'base' => 'node', |
377 |
// The name of the field on the joined table.
|
378 |
'base field' => 'nid', |
379 |
// 'field' => 'nid' -- see hook_views_data_alter(); not needed here.
|
380 |
'handler' => 'views_handler_relationship', |
381 |
'label' => t('Default label for the relationship'), |
382 |
'title' => t('Title shown when adding the relationship'), |
383 |
'help' => t('More information on this relationship'), |
384 |
), |
385 |
); |
386 |
|
387 |
// Example plain text field.
|
388 |
$data['example_table']['plain_text_field'] = array( |
389 |
'title' => t('Plain text field'), |
390 |
'help' => t('Just a plain text field.'), |
391 |
'field' => array( |
392 |
'handler' => 'views_handler_field', |
393 |
// This is use by the table display plugin.
|
394 |
'click sortable' => TRUE, |
395 |
), |
396 |
'sort' => array( |
397 |
'handler' => 'views_handler_sort', |
398 |
), |
399 |
'filter' => array( |
400 |
'handler' => 'views_handler_filter_string', |
401 |
), |
402 |
'argument' => array( |
403 |
'handler' => 'views_handler_argument_string', |
404 |
), |
405 |
); |
406 |
|
407 |
// Example numeric text field.
|
408 |
$data['example_table']['numeric_field'] = array( |
409 |
'title' => t('Numeric field'), |
410 |
'help' => t('Just a numeric field.'), |
411 |
'field' => array( |
412 |
'handler' => 'views_handler_field_numeric', |
413 |
'click sortable' => TRUE, |
414 |
), |
415 |
'filter' => array( |
416 |
'handler' => 'views_handler_filter_numeric', |
417 |
), |
418 |
'sort' => array( |
419 |
'handler' => 'views_handler_sort', |
420 |
), |
421 |
); |
422 |
|
423 |
// Example boolean field.
|
424 |
$data['example_table']['boolean_field'] = array( |
425 |
'title' => t('Boolean field'), |
426 |
'help' => t('Just an on/off field.'), |
427 |
'field' => array( |
428 |
'handler' => 'views_handler_field_boolean', |
429 |
'click sortable' => TRUE, |
430 |
), |
431 |
'filter' => array( |
432 |
'handler' => 'views_handler_filter_boolean_operator', |
433 |
// Note that you can override the field-wide label.
|
434 |
'label' => t('Published'), |
435 |
// This setting is used by the boolean filter handler, as possible option.
|
436 |
'type' => 'yes-no', |
437 |
// use boolean_field = 1 instead of boolean_field <> 0 in WHERE statement.
|
438 |
'use equal' => TRUE, |
439 |
), |
440 |
'sort' => array( |
441 |
'handler' => 'views_handler_sort', |
442 |
), |
443 |
); |
444 |
|
445 |
// Example timestamp field.
|
446 |
$data['example_table']['timestamp_field'] = array( |
447 |
'title' => t('Timestamp field'), |
448 |
'help' => t('Just a timestamp field.'), |
449 |
'field' => array( |
450 |
'handler' => 'views_handler_field_date', |
451 |
'click sortable' => TRUE, |
452 |
), |
453 |
'sort' => array( |
454 |
'handler' => 'views_handler_sort_date', |
455 |
), |
456 |
'filter' => array( |
457 |
'handler' => 'views_handler_filter_date', |
458 |
), |
459 |
); |
460 |
|
461 |
return $data; |
462 |
} |
463 |
|
464 |
/**
|
465 |
* Alter table structure.
|
466 |
*
|
467 |
* You can add/edit/remove existing tables defined by hook_views_data().
|
468 |
*
|
469 |
* This hook should be placed in MODULENAME.views.inc and it will be
|
470 |
* auto-loaded. MODULENAME.views.inc must be in the directory specified by the
|
471 |
* 'path' key returned by MODULENAME_views_api(), or the same directory as the
|
472 |
* .module file, if 'path' is unspecified.
|
473 |
*
|
474 |
* @param array $data
|
475 |
* An array of all Views data, passed by reference. See hook_views_data() for
|
476 |
* structure.
|
477 |
*
|
478 |
* @see hook_views_data()
|
479 |
*/
|
480 |
function hook_views_data_alter(&$data) { |
481 |
// This example alters the title of the node:nid field in the Views UI.
|
482 |
$data['node']['nid']['title'] = t('Node-Nid'); |
483 |
|
484 |
// This example adds an example field to the users table.
|
485 |
$data['users']['example_field'] = array( |
486 |
'title' => t('Example field'), |
487 |
'help' => t('Some example content that references a user'), |
488 |
'field' => array( |
489 |
'handler' => 'modulename_handler_field_example_field', |
490 |
), |
491 |
); |
492 |
|
493 |
// This example changes the handler of the node title field.
|
494 |
// In this handler you could do stuff, like preview of the node when clicking
|
495 |
// the node title.
|
496 |
$data['node']['title']['field']['handler'] = 'modulename_handler_field_node_title'; |
497 |
|
498 |
// This example adds a relationship to table {foo}, so that 'foo' views can
|
499 |
// add this table using a relationship. Because we don't want to write over
|
500 |
// the primary key field definition for the {foo}.fid field, we use a dummy
|
501 |
// field name as the key.
|
502 |
$data['foo']['dummy_name'] = array( |
503 |
'title' => t('Example relationship'), |
504 |
'help' => t('Example help'), |
505 |
'relationship' => array( |
506 |
// Table we're joining to.
|
507 |
'base' => 'example_table', |
508 |
// Field on the joined table.
|
509 |
'base field' => 'eid', |
510 |
// Real field name on the 'foo' table.
|
511 |
'field' => 'fid', |
512 |
'handler' => 'views_handler_relationship', |
513 |
'label' => t('Default label for relationship'), |
514 |
'title' => t('Title seen when adding relationship'), |
515 |
'help' => t('More information about relationship.'), |
516 |
), |
517 |
); |
518 |
|
519 |
// Note that the $data array is not returned – it is modified by reference.
|
520 |
} |
521 |
|
522 |
/**
|
523 |
* Override the default data for a Field API field.
|
524 |
*
|
525 |
* Field module's Implements hook_views_data() invokes this for each
|
526 |
* field in the module that defines the field type (as declared in the field
|
527 |
* array). It is not invoked in other modules.
|
528 |
*
|
529 |
* If no hook implementation exists, hook_views_data() falls back to
|
530 |
* field_views_field_default_views_data().
|
531 |
*
|
532 |
* @param array $field
|
533 |
* A field definition array, as returned by field_info_fields().
|
534 |
*
|
535 |
* @return array
|
536 |
* An array of views data, in the same format as the return value of
|
537 |
* hook_views_data().
|
538 |
*
|
539 |
* @see field_views_data()
|
540 |
* @see hook_field_views_data_alter()
|
541 |
* @see hook_field_views_data_views_data_alter()
|
542 |
*/
|
543 |
function hook_field_views_data($field) { |
544 |
return array(); |
545 |
} |
546 |
|
547 |
/**
|
548 |
* Alter the views data for a single Field API field.
|
549 |
*
|
550 |
* This is called even if there is no hook_field_views_data() implementation for
|
551 |
* the field, and therefore may be used to alter the default data that
|
552 |
* field_views_field_default_views_data() supplies for the field.
|
553 |
*
|
554 |
* @param array $result
|
555 |
* An array of views table data provided for a single field. This has the same
|
556 |
* format as the return value of hook_views_data().
|
557 |
* @param array $field
|
558 |
* A field definition array, as returned by field_info_fields().
|
559 |
* @param string $module
|
560 |
* The module that defines the field type.
|
561 |
*
|
562 |
* @see field_views_data()
|
563 |
* @see hook_field_views_data()
|
564 |
* @see hook_field_views_data_views_data_alter()
|
565 |
*/
|
566 |
function hook_field_views_data_alter(&$result, $field, $module) { |
567 |
|
568 |
} |
569 |
|
570 |
/**
|
571 |
* Alter the views data on a per field basis.
|
572 |
*
|
573 |
* Field module's Implements hook_views_data_alter() invokes this for
|
574 |
* each field in the module that defines the field type (as declared in the
|
575 |
* field array). It is not invoked in other modules.
|
576 |
*
|
577 |
* Unlike hook_field_views_data_alter(), this operates on the whole of the views
|
578 |
* data. This allows a field module to add data that concerns its fields to
|
579 |
* other tables, which would not yet be defined at the point when
|
580 |
* hook_field_views_data() and hook_field_views_data_alter() are invoked. For
|
581 |
* example, entityreference adds reverse relationships on the tables for the
|
582 |
* entities which are referenced by entityreference fields.
|
583 |
*
|
584 |
* (Note: this is weirdly named so as not to conflict with
|
585 |
* hook_field_views_data_alter().)
|
586 |
*
|
587 |
* @see hook_field_views_data()
|
588 |
* @see hook_field_views_data_alter()
|
589 |
* @see field_views_data_alter()
|
590 |
*/
|
591 |
function hook_field_views_data_views_data_alter(&$data, $field) { |
592 |
$field_name = $field['field_name']; |
593 |
$data_key = 'field_data_' . $field_name; |
594 |
// Views data for this field is in $data[$data_key]
|
595 |
} |
596 |
|
597 |
/**
|
598 |
* Describes plugins defined by the module.
|
599 |
*
|
600 |
* This hook should be placed in MODULENAME.views.inc and it will be
|
601 |
* auto-loaded. MODULENAME.views.inc must be in the directory specified by the
|
602 |
* 'path' key returned by MODULENAME_views_api(), or the same directory as the
|
603 |
* .module file, if 'path' is unspecified. All plugin files need to be
|
604 |
* referenced in MODULENAME.info with the files[] directive.
|
605 |
*
|
606 |
* @return array
|
607 |
* An array on the form $plugins['PLUGIN TYPE']['PLUGIN NAME']. The plugin
|
608 |
* must be one of row, display, display_extender, style, argument default,
|
609 |
* argument validator, access, query, cache, pager, exposed_form or
|
610 |
* localization. The plugin name should be prefixed with your module name.
|
611 |
* The value for each entry is an associative array that may contain the
|
612 |
* following entries:
|
613 |
* - Used by all plugin types:
|
614 |
* - title (required): The name of the plugin, as shown in Views. Wrap in
|
615 |
* t().
|
616 |
* - handler (required): The name of the file containing the class
|
617 |
* describing the handler, which must also be the name of the handler's
|
618 |
* class.
|
619 |
* - path: Path to the handler. Only required if the handler is not placed
|
620 |
* in the same folder as the .module file or in the subfolder 'views'.
|
621 |
* - parent: The name of the plugin this plugin extends. Since Drupal 7 this
|
622 |
* is no longer required, but may still be useful from a code readability
|
623 |
* perspective.
|
624 |
* - no ui: Set to TRUE to denote that the plugin doesn't appear to be
|
625 |
* selectable in the ui, though on the api side they still exists.
|
626 |
* - uses options: Set to TRUE to denote that the plugin has an additional
|
627 |
* options form.
|
628 |
* - help: A short help text, wrapped in t() used as description on the
|
629 |
* plugin settings form.
|
630 |
* - help topic: The name of an entry by advanced help for the plugin.
|
631 |
* - theme: The name of a theme suggestion to use for the display.
|
632 |
* - js: An array with paths to js files that should be included for the
|
633 |
* display. Note that the path should be relative Drupal root, not module
|
634 |
* root.
|
635 |
* - type: Each plugin can specify a type parameter to group certain
|
636 |
* plugins together. For example all row plugins related to feeds are
|
637 |
* grouped together, because a rss style plugin only accepts feed row
|
638 |
* plugins.
|
639 |
*
|
640 |
* - Used by display plugins:
|
641 |
* - admin: The administrative name of the display, as displayed on the
|
642 |
* Views overview and also used as default name for new displays. Wrap in
|
643 |
* t().
|
644 |
* - no remove: Set to TRUE to make the display non-removable. (Basically
|
645 |
* only used for the master/default display.)
|
646 |
* - use ajax: Set to TRUE to allow AJAX loads in the display. If it's
|
647 |
* disabled there will be no ajax option in the ui.
|
648 |
* - use pager: Set to TRUE to allow paging in the display.
|
649 |
* - use more: Set to TRUE to allow the 'use more' setting in the display.
|
650 |
* - accept attachments: Set to TRUE to allow attachment displays to be
|
651 |
* attached to this display type.
|
652 |
* - contextual links locations: An array with places where contextual links
|
653 |
* should be added. Can for example be 'page' or 'block'. If you don't
|
654 |
* specify it there will be contextual links around the rendered view. If
|
655 |
* this is not set or regions have been specified, views will display an
|
656 |
* option to 'hide contextual links'. Use an empty array if you do not
|
657 |
* want this.
|
658 |
* - uses hook menu: Set to TRUE to have the display included by
|
659 |
* views_menu_alter(). views_menu_alter executes then execute_hook_menu
|
660 |
* on the display object.
|
661 |
* - uses hook block: Set to TRUE to have the display included by
|
662 |
* views_block_info().
|
663 |
* - theme: The name of a theme suggestion to use for the display.
|
664 |
* - js: An array with paths to js files that should be included for the
|
665 |
* display. Note that the path should be relative Drupal root, not module
|
666 |
* root.
|
667 |
*
|
668 |
* - Used by style plugins:
|
669 |
* - uses row plugin: Set to TRUE to allow row plugins for this style.
|
670 |
* - uses row class: Set to TRUE to allow the CSS class settings for rows.
|
671 |
* - uses fields: Set to TRUE to have the style plugin accept field
|
672 |
* handlers.
|
673 |
* - uses grouping: Set to TRUE to allow the grouping settings for rows.
|
674 |
* - even empty: May have the value 'even empty' to tell Views that the
|
675 |
* style should be rendered even if there are no results.
|
676 |
*
|
677 |
* - Used by row plugins:
|
678 |
* - uses fields: Set to TRUE to have the row plugin accept field handlers.
|
679 |
*/
|
680 |
function hook_views_plugins() { |
681 |
$plugins = array(); |
682 |
$plugins['argument validator'] = array( |
683 |
'taxonomy_term' => array( |
684 |
'title' => t('Taxonomy term'), |
685 |
'handler' => 'views_plugin_argument_validate_taxonomy_term', |
686 |
// Declaring path explicitly not necessary for most modules.
|
687 |
'path' => drupal_get_path('module', 'views') . '/modules/taxonomy', |
688 |
), |
689 |
); |
690 |
|
691 |
return array( |
692 |
// This just tells our themes are elsewhere.
|
693 |
'module' => 'views', |
694 |
'argument validator' => array( |
695 |
'taxonomy_term' => array( |
696 |
'title' => t('Taxonomy term'), |
697 |
'handler' => 'views_plugin_argument_validate_taxonomy_term', |
698 |
// Declaring path explicitly not necessary for most modules.
|
699 |
'path' => drupal_get_path('module', 'views') . '/modules/taxonomy', |
700 |
), |
701 |
), |
702 |
'argument default' => array( |
703 |
'taxonomy_tid' => array( |
704 |
'title' => t('Taxonomy term ID from URL'), |
705 |
'handler' => 'views_plugin_argument_default_taxonomy_tid', |
706 |
'path' => drupal_get_path('module', 'views') . '/modules/taxonomy', |
707 |
'parent' => 'fixed', |
708 |
), |
709 |
), |
710 |
); |
711 |
} |
712 |
|
713 |
/**
|
714 |
* Alter existing plugins data, defined by modules.
|
715 |
*
|
716 |
* @see hook_views_plugins()
|
717 |
*/
|
718 |
function hook_views_plugins_alter(&$plugins) { |
719 |
// Add apachesolr to the base of the node row plugin.
|
720 |
$plugins['row']['node']['base'][] = 'apachesolr'; |
721 |
} |
722 |
|
723 |
/**
|
724 |
* Alter existing plugin option definitions.
|
725 |
*
|
726 |
* This can be used to edit default or add new option definitions to existing
|
727 |
* plugins. The reason for doing this is that only overriding the relevent form
|
728 |
* with hook_form_alter() is insufficent because submitted form values will be
|
729 |
* ignored if they haven't been declared as an available option.
|
730 |
*
|
731 |
* An alternative approach you could also take is to extend each plugin
|
732 |
* individually. However if your goal is to override many, or even all plugins,
|
733 |
* this results in a lot of additional code and files. This makes it a lot more
|
734 |
* troublesome to maintain the codebase, as well as interoperability with other
|
735 |
* modules.
|
736 |
*
|
737 |
* @param array $options
|
738 |
* The option definitions to be altered.
|
739 |
* @param $plugin
|
740 |
* A views object of the plugin where the default options are defined.
|
741 |
*
|
742 |
* @see views_object::option_definition()
|
743 |
* @see hook_views_handler_option_definition_alter()
|
744 |
* @see hook_form_alter()
|
745 |
*/
|
746 |
function hook_views_plugin_option_definition_alter(&$options, $plugin) { |
747 |
// Add a new option definition.
|
748 |
$options['option_name'] = array('default' => ''); |
749 |
} |
750 |
|
751 |
/**
|
752 |
* Alter existing handler option definitions.
|
753 |
*
|
754 |
* This can be used to edit default or add new option definitions to existing
|
755 |
* handlers. The reason for doing this is that only overriding the relevent form
|
756 |
* with hook_form_alter() is insufficent because submitted form values will be
|
757 |
* ignored if they haven't been declared as an available option.
|
758 |
*
|
759 |
* An alternative approach you could also take is to extend each handler
|
760 |
* individually. However if your goal is to override many, or even all handlers,
|
761 |
* this results in a lot of additional code and files. This makes it a lot more
|
762 |
* troublesome to maintain the codebase, as well as interoperability with other
|
763 |
* modules.
|
764 |
*
|
765 |
* @param array $options
|
766 |
* The option definitions to be altered.
|
767 |
* @param $handler
|
768 |
* A views object of the handler where the default options are defined.
|
769 |
*
|
770 |
* @see views_handler::option_definition()
|
771 |
* @see hook_views_plugin_option_definition_alter()
|
772 |
* @see hook_form_alter()
|
773 |
*/
|
774 |
function hook_views_handler_option_definition_alter(&$options, $handler) { |
775 |
// Add a new option definition.
|
776 |
$options['option_name'] = array('default' => ''); |
777 |
} |
778 |
|
779 |
/**
|
780 |
* Register View API information.
|
781 |
*
|
782 |
* This is required for your module to have its include files loaded; for
|
783 |
* example, when implementing hook_views_default_views().
|
784 |
*
|
785 |
* @return array
|
786 |
* An array with the following possible keys:
|
787 |
* - api: (required) The version of the Views API the module implements.
|
788 |
* - path: (optional) If includes are stored somewhere other than within the
|
789 |
* root module directory, specify its path here.
|
790 |
* - template path: (optional) A path where the module has stored its views
|
791 |
* template files. When you have specified this key views automatically
|
792 |
* uses the template files for the views. You can use the same naming
|
793 |
* conventions like for normal views template files.
|
794 |
*/
|
795 |
function hook_views_api() { |
796 |
return array( |
797 |
'api' => 3, |
798 |
'path' => drupal_get_path('module', 'example') . '/includes/views', |
799 |
'template path' => drupal_get_path('module', 'example') . '/themes', |
800 |
); |
801 |
} |
802 |
|
803 |
/**
|
804 |
* Allows modules to provide their own views.
|
805 |
*
|
806 |
* These can either be used as-is or as a "starter" for users to build from.
|
807 |
*
|
808 |
* This hook should be placed in MODULENAME.views_default.inc and it will be
|
809 |
* auto-loaded. MODULENAME.views_default.inc must be in the directory specified
|
810 |
* by the 'path' key returned by MODULENAME_views_api(), or the same directory
|
811 |
* as the .module file, if 'path' is unspecified.
|
812 |
*
|
813 |
* The $view->disabled boolean flag indicates whether the View should be
|
814 |
* enabled (FALSE) or disabled (TRUE) by default.
|
815 |
*
|
816 |
* @return array
|
817 |
* An associative array containing the structures of views, as generated from
|
818 |
* the Export tab, keyed by the view name. A best practice is to go through
|
819 |
* and add t() to all title and label strings, with the exception of menu
|
820 |
* strings.
|
821 |
*/
|
822 |
function hook_views_default_views() { |
823 |
// Begin copy and paste of output from the Export tab of a view.
|
824 |
$view = new view(); |
825 |
$view->name = 'frontpage'; |
826 |
$view->description = 'Emulates the default Drupal front page; you may set the default home page path to this view to make it your front page.'; |
827 |
$view->tag = 'default'; |
828 |
$view->base_table = 'node'; |
829 |
$view->human_name = 'Front page'; |
830 |
$view->core = 0; |
831 |
$view->api_version = '3.0'; |
832 |
$view->disabled = FALSE; /* Edit this to true to make a default view disabled initially */ |
833 |
|
834 |
/* Display: Master */
|
835 |
$handler = $view->new_display('default', 'Master', 'default'); |
836 |
$handler->display->display_options['access']['type'] = 'none'; |
837 |
$handler->display->display_options['cache']['type'] = 'none'; |
838 |
$handler->display->display_options['query']['type'] = 'views_query'; |
839 |
$handler->display->display_options['query']['options']['query_comment'] = FALSE; |
840 |
$handler->display->display_options['exposed_form']['type'] = 'basic'; |
841 |
$handler->display->display_options['pager']['type'] = 'full'; |
842 |
$handler->display->display_options['style_plugin'] = 'default'; |
843 |
$handler->display->display_options['row_plugin'] = 'node'; |
844 |
/* Sort criterion: Content: Sticky */
|
845 |
$handler->display->display_options['sorts']['sticky']['id'] = 'sticky'; |
846 |
$handler->display->display_options['sorts']['sticky']['table'] = 'node'; |
847 |
$handler->display->display_options['sorts']['sticky']['field'] = 'sticky'; |
848 |
$handler->display->display_options['sorts']['sticky']['order'] = 'DESC'; |
849 |
/* Sort criterion: Content: Post date */
|
850 |
$handler->display->display_options['sorts']['created']['id'] = 'created'; |
851 |
$handler->display->display_options['sorts']['created']['table'] = 'node'; |
852 |
$handler->display->display_options['sorts']['created']['field'] = 'created'; |
853 |
$handler->display->display_options['sorts']['created']['order'] = 'DESC'; |
854 |
/* Filter criterion: Content: Promoted to front page */
|
855 |
$handler->display->display_options['filters']['promote']['id'] = 'promote'; |
856 |
$handler->display->display_options['filters']['promote']['table'] = 'node'; |
857 |
$handler->display->display_options['filters']['promote']['field'] = 'promote'; |
858 |
$handler->display->display_options['filters']['promote']['value'] = '1'; |
859 |
$handler->display->display_options['filters']['promote']['group'] = 0; |
860 |
$handler->display->display_options['filters']['promote']['expose']['operator'] = FALSE; |
861 |
/* Filter criterion: Content: Published */
|
862 |
$handler->display->display_options['filters']['status']['id'] = 'status'; |
863 |
$handler->display->display_options['filters']['status']['table'] = 'node'; |
864 |
$handler->display->display_options['filters']['status']['field'] = 'status'; |
865 |
$handler->display->display_options['filters']['status']['value'] = '1'; |
866 |
$handler->display->display_options['filters']['status']['group'] = 0; |
867 |
$handler->display->display_options['filters']['status']['expose']['operator'] = FALSE; |
868 |
|
869 |
/* Display: Page */
|
870 |
$handler = $view->new_display('page', 'Page', 'page'); |
871 |
$handler->display->display_options['path'] = 'frontpage'; |
872 |
|
873 |
/* Display: Feed */
|
874 |
$handler = $view->new_display('feed', 'Feed', 'feed'); |
875 |
$handler->display->display_options['defaults']['title'] = FALSE; |
876 |
$handler->display->display_options['title'] = 'Front page feed'; |
877 |
$handler->display->display_options['pager']['type'] = 'some'; |
878 |
$handler->display->display_options['style_plugin'] = 'rss'; |
879 |
$handler->display->display_options['row_plugin'] = 'node_rss'; |
880 |
$handler->display->display_options['path'] = 'rss.xml'; |
881 |
$handler->display->display_options['displays'] = array( |
882 |
'default' => 'default', |
883 |
'page' => 'page', |
884 |
); |
885 |
$handler->display->display_options['sitename_title'] = '1'; |
886 |
|
887 |
// (Export ends here.)
|
888 |
// Add view to list of views to provide.
|
889 |
$views[$view->name] = $view; |
890 |
|
891 |
// Repeat all of the above for each view the module should provide. At the
|
892 |
// end, return array of default views.
|
893 |
return $views; |
894 |
} |
895 |
|
896 |
/**
|
897 |
* Alter default views defined by other modules.
|
898 |
*
|
899 |
* This hook is called right before all default views are cached to the
|
900 |
* database. It takes a keyed array of views by reference.
|
901 |
*
|
902 |
* Example usage to add a field to a view:
|
903 |
* @code
|
904 |
* $handler =& $view->display['DISPLAY_ID']->handler;
|
905 |
* // Add the user name field to the view.
|
906 |
* $handler->display->display_options['fields']['name']['id'] = 'name';
|
907 |
* $handler->display->display_options['fields']['name']['table'] = 'users';
|
908 |
* $handler->display->display_options['fields']['name']['field'] = 'name';
|
909 |
* $handler->display->display_options['fields']['name']['label'] = 'Author';
|
910 |
* $handler->display->display_options['fields']['name']['link_to_user'] = 1;
|
911 |
* @endcode
|
912 |
*/
|
913 |
function hook_views_default_views_alter(&$views) { |
914 |
if (isset($views['taxonomy_term'])) { |
915 |
$views['taxonomy_term']->display['default']->display_options['title'] = 'Categories'; |
916 |
} |
917 |
} |
918 |
|
919 |
/**
|
920 |
* Performs replacements in the query before being performed.
|
921 |
*
|
922 |
* @param object $view
|
923 |
* The View being executed.
|
924 |
*
|
925 |
* @return array
|
926 |
* An array with keys being the strings to replace, and the values the strings
|
927 |
* to replace them with. The strings to replace are often surrounded with
|
928 |
* '***', as illustrated in the example implementation.
|
929 |
*/
|
930 |
function hook_views_query_substitutions($view) { |
931 |
// Example from views_views_query_substitutions().
|
932 |
global $language_content; |
933 |
return array( |
934 |
'***CURRENT_VERSION***' => VERSION, |
935 |
'***CURRENT_TIME***' => REQUEST_TIME, |
936 |
'***CURRENT_LANGUAGE***' => $language_content->language, |
937 |
'***DEFAULT_LANGUAGE***' => language_default('language'), |
938 |
); |
939 |
} |
940 |
|
941 |
/**
|
942 |
* This hook is called to get a list of placeholders and their substitutions.
|
943 |
*
|
944 |
* Used when preprocessing a View with form elements.
|
945 |
*
|
946 |
* @return array
|
947 |
* An array with keys being the strings to replace, and the values the strings
|
948 |
* to replace them with.
|
949 |
*/
|
950 |
function hook_views_form_substitutions() { |
951 |
return array( |
952 |
'<!--views-form-example-substitutions-->' => 'Example Substitution', |
953 |
); |
954 |
} |
955 |
|
956 |
/**
|
957 |
* Allows altering a view at the very beginning of processing a preview.
|
958 |
*
|
959 |
* Occurs before anything is done.
|
960 |
*
|
961 |
* This hook is only triggered when the one of the following are invoked:
|
962 |
* - $view->execute_display()
|
963 |
* - $view->preview()
|
964 |
*
|
965 |
* As such code placed in this hook will not fire during:
|
966 |
* - $view->build()
|
967 |
* - $view->execute()
|
968 |
* - $view->render()
|
969 |
*
|
970 |
* Likely, hook_views_pre_build() or hook_views_pre_execute() are much better
|
971 |
* choices for most use cases since they are always invoked, not just when
|
972 |
* previewing a display.
|
973 |
*
|
974 |
* Adding output to the view can be accomplished by placing text on
|
975 |
* $view->attachment_before and $view->attachment_after.
|
976 |
*
|
977 |
* @param object $view
|
978 |
* The view object about to be processed.
|
979 |
* @param string $display_id
|
980 |
* The machine name of the active display.
|
981 |
* @param array $args
|
982 |
* An array of arguments passed into the view.
|
983 |
*/
|
984 |
function hook_views_pre_view(&$view, &$display_id, &$args) { |
985 |
// Change the display if the acting user has 'administer site configuration'
|
986 |
// permission, to display something radically different.
|
987 |
// (Note that this is not necessarily the best way to solve that task. Feel
|
988 |
// free to contribute another example!)
|
989 |
if (
|
990 |
$view->name == 'my_special_view' |
991 |
&& user_access('administer site configuration')
|
992 |
&& $display_id == 'public_display' |
993 |
) { |
994 |
$view->set_display('private_display'); |
995 |
} |
996 |
} |
997 |
|
998 |
/**
|
999 |
* Called after the display's pre_execute phase but before the build process.
|
1000 |
*
|
1001 |
* Adding output to the view can be accomplished by placing text on
|
1002 |
* $view->attachment_before and $view->attachment_after.
|
1003 |
*
|
1004 |
* @param object $view
|
1005 |
* The view object about to be processed.
|
1006 |
*/
|
1007 |
function hook_views_pre_build(&$view) { |
1008 |
// Because of some inexplicable business logic, we should remove all
|
1009 |
// attachments from all views on Mondays.
|
1010 |
// (This alter could be done later in the execution process as well.)
|
1011 |
if (date('D') == 'Mon') { |
1012 |
unset($view->attachment_before); |
1013 |
unset($view->attachment_after); |
1014 |
} |
1015 |
} |
1016 |
|
1017 |
/**
|
1018 |
* This hook is called right after the build process.
|
1019 |
*
|
1020 |
* The query is now fully built, but it has not yet been run through
|
1021 |
* db_rewrite_sql.
|
1022 |
*
|
1023 |
* Adding output to the view can be accomplished by placing text on
|
1024 |
* $view->attachment_before and $view->attachment_after.
|
1025 |
*
|
1026 |
* @param object $view
|
1027 |
* The view object about to be processed.
|
1028 |
*/
|
1029 |
function hook_views_post_build(&$view) { |
1030 |
// If the exposed field 'type' is set, hide the column containing the content
|
1031 |
// type. (Note that this is a solution for a particular view, and makes
|
1032 |
// assumptions about both exposed filter settings and the fields in the view.
|
1033 |
// Also note that this alter could be done at any point before the view being
|
1034 |
// rendered.)
|
1035 |
if ($view->name == 'my_view' && isset($view->exposed_raw_input['type']) && $view->exposed_raw_input['type'] != 'All') { |
1036 |
// 'Type' should be interpreted as content type.
|
1037 |
if (isset($view->field['type'])) { |
1038 |
$view->field['type']->options['exclude'] = TRUE; |
1039 |
} |
1040 |
} |
1041 |
} |
1042 |
|
1043 |
/**
|
1044 |
* This hook is called right before the execute process.
|
1045 |
*
|
1046 |
* The query is now fully built, but it has not yet been run through
|
1047 |
* db_rewrite_sql.
|
1048 |
*
|
1049 |
* Adding output to the view can be accomplished by placing text on
|
1050 |
* $view->attachment_before and $view->attachment_after.
|
1051 |
*
|
1052 |
* @param object $view
|
1053 |
* The view object about to be processed.
|
1054 |
*/
|
1055 |
function hook_views_pre_execute(&$view) { |
1056 |
// Whenever a view queries more than two tables, show a message that notifies
|
1057 |
// view administrators that the query might be heavy.
|
1058 |
// (This action could be performed later in the execution process, but not
|
1059 |
// earlier.)
|
1060 |
if (count($view->query->tables) > 2 && user_access('administer views')) { |
1061 |
drupal_set_message(t('The view %view may be heavy to execute.', array('%view' => $view->name)), 'warning'); |
1062 |
} |
1063 |
} |
1064 |
|
1065 |
/**
|
1066 |
* This hook is called right after the execute process.
|
1067 |
*
|
1068 |
* The query has been executed, but the pre_render() phase has not yet happened
|
1069 |
* for handlers.
|
1070 |
*
|
1071 |
* Adding output to the view can be accomplished by placing text on
|
1072 |
* $view->attachment_before and $view->attachment_after. Altering the content
|
1073 |
* can be achieved by editing the items of $view->result.
|
1074 |
*
|
1075 |
* @param object $view
|
1076 |
* The view object about to be processed.
|
1077 |
*/
|
1078 |
function hook_views_post_execute(&$view) { |
1079 |
// If there are more than 100 results, show a message that encourages the user
|
1080 |
// to change the filter settings.
|
1081 |
// (This action could be performed later in the execution process, but not
|
1082 |
// earlier.)
|
1083 |
if ($view->total_rows > 100) { |
1084 |
drupal_set_message(t('You have more than 100 hits. Use the filter settings to narrow down your list.'));
|
1085 |
} |
1086 |
} |
1087 |
|
1088 |
/**
|
1089 |
* This hook is called right before the render process.
|
1090 |
*
|
1091 |
* The query has been executed, and the pre_render() phase has already happened
|
1092 |
* for handlers, so all data should be available.
|
1093 |
*
|
1094 |
* Adding output to the view can be accomplished by placing text on
|
1095 |
* $view->attachment_before and $view->attachment_after. Altering the content
|
1096 |
* can be achieved by editing the items of $view->result.
|
1097 |
*
|
1098 |
* This hook can be utilized by themes.
|
1099 |
*
|
1100 |
* @param object $view
|
1101 |
* The view object about to be processed.
|
1102 |
*/
|
1103 |
function hook_views_pre_render(&$view) { |
1104 |
// Scramble the order of the rows shown on this result page.
|
1105 |
// Note that this could be done earlier, but not later in the view execution
|
1106 |
// process.
|
1107 |
shuffle($view->result); |
1108 |
} |
1109 |
|
1110 |
/**
|
1111 |
* Post process any rendered data.
|
1112 |
*
|
1113 |
* This can be valuable to be able to cache a view and still have some level of
|
1114 |
* dynamic output. In an ideal world, the actual output will include HTML
|
1115 |
* comment based tokens, and then the post process can replace those tokens.
|
1116 |
*
|
1117 |
* Example usage. If it is known that the view is a node view and that the
|
1118 |
* primary field will be a nid, you can do something like this:
|
1119 |
*
|
1120 |
* <!--post-FIELD-NID-->
|
1121 |
*
|
1122 |
* And then in the post render, create an array with the text that should
|
1123 |
* go there:
|
1124 |
*
|
1125 |
* strtr($output, array('<!--post-FIELD-1-->' => 'output for FIELD of nid 1');
|
1126 |
*
|
1127 |
* All of the cached result data will be available in $view->result, as well,
|
1128 |
* so all ids used in the query should be discoverable.
|
1129 |
*
|
1130 |
* This hook can be utilized by themes.
|
1131 |
*
|
1132 |
* @param object $view
|
1133 |
* The view object about to be processed.
|
1134 |
* @param string $output
|
1135 |
* A flat string with the rendered output of the view.
|
1136 |
* @param array $cache
|
1137 |
* The cache settings.
|
1138 |
*/
|
1139 |
function hook_views_post_render(&$view, &$output, &$cache) { |
1140 |
// When using full pager, disable any time-based caching if there are less
|
1141 |
// then 10 results.
|
1142 |
if ($view->query->pager instanceof views_plugin_pager_full && $cache->options['type'] == 'time' && count($view->result) < 10) { |
1143 |
$cache['options']['results_lifespan'] = 0; |
1144 |
$cache['options']['output_lifespan'] = 0; |
1145 |
} |
1146 |
} |
1147 |
|
1148 |
/**
|
1149 |
* Alter the query before executing the query.
|
1150 |
*
|
1151 |
* This hook should be placed in MODULENAME.views.inc and it will be
|
1152 |
* auto-loaded. MODULENAME.views.inc must be in the directory specified by the
|
1153 |
* 'path' key returned by MODULENAME_views_api(), or the same directory as the
|
1154 |
* .module file, if 'path' is unspecified.
|
1155 |
*
|
1156 |
* @param object $view
|
1157 |
* The view object about to be processed.
|
1158 |
* @param object $query
|
1159 |
* An object describing the query.
|
1160 |
*
|
1161 |
* @see hook_views_query_substitutions()
|
1162 |
*/
|
1163 |
function hook_views_query_alter(&$view, &$query) { |
1164 |
// (Example assuming a view with an exposed filter on node title.)
|
1165 |
// If the input for the title filter is a positive integer, filter against
|
1166 |
// node ID instead of node title.
|
1167 |
if ($view->name == 'my_view' && is_numeric($view->exposed_raw_input['title']) && $view->exposed_raw_input['title'] > 0) { |
1168 |
// Traverse through the 'where' part of the query.
|
1169 |
foreach ($query->where as &$condition_group) { |
1170 |
foreach ($condition_group['conditions'] as &$condition) { |
1171 |
// If this is the part of the query filtering on title, change the
|
1172 |
// condition to filter on node ID.
|
1173 |
if ($condition['field'] == 'node.title') { |
1174 |
$condition = array( |
1175 |
'field' => 'node.nid', |
1176 |
'value' => $view->exposed_raw_input['title'], |
1177 |
'operator' => '=', |
1178 |
); |
1179 |
} |
1180 |
} |
1181 |
} |
1182 |
} |
1183 |
} |
1184 |
|
1185 |
/**
|
1186 |
* Alter the information box that (optionally) appears with a view preview.
|
1187 |
*
|
1188 |
* Includes query and performance statistics.
|
1189 |
*
|
1190 |
* This hook should be placed in MODULENAME.views.inc and it will be
|
1191 |
* auto-loaded. MODULENAME.views.inc must be in the directory specified by the
|
1192 |
* 'path' key returned by MODULENAME_views_api(), or the same directory as the
|
1193 |
* .module file, if 'path' is unspecified.
|
1194 |
*
|
1195 |
* Warning: $view is not a reference in PHP4 and cannot be modified here. But it
|
1196 |
* IS a reference in PHP5, and can be modified. Please be careful with it.
|
1197 |
*
|
1198 |
* @param array $rows
|
1199 |
* An associative array with two keys:
|
1200 |
* - query: An array of rows suitable for theme('table'), containing
|
1201 |
* information about the query and the display title and path.
|
1202 |
* - statistics: An array of rows suitable for theme('table'), containing
|
1203 |
* performance statistics.
|
1204 |
* @param object $view
|
1205 |
* The view object.
|
1206 |
*
|
1207 |
* @see theme_table()
|
1208 |
*/
|
1209 |
function hook_views_preview_info_alter(&$rows, $view) { |
1210 |
// Adds information about the tables being queried by the view to the query
|
1211 |
// part of the info box.
|
1212 |
$rows['query'][] = array( |
1213 |
t('<strong>Table queue</strong>'),
|
1214 |
count($view->query->table_queue) . ': (' . implode(', ', array_keys($view->query->table_queue)) . ')', |
1215 |
); |
1216 |
} |
1217 |
|
1218 |
/**
|
1219 |
* This hooks allows to alter the links at the top of the view edit form.
|
1220 |
*
|
1221 |
* Some modules might want to add links there.
|
1222 |
*
|
1223 |
* @param array $links
|
1224 |
* An array of links which will be displayed at the top of the view edit form.
|
1225 |
* Each entry should be on a form suitable for theme('link').
|
1226 |
* @param object $view
|
1227 |
* The full view object which is currently edited.
|
1228 |
* @param string $display_id
|
1229 |
* The current display id which is edited. For example that's 'default' or
|
1230 |
* 'page_1'.
|
1231 |
*/
|
1232 |
function hook_views_ui_display_top_links_alter(&$links, $view, $display_id) { |
1233 |
// Put the export link first in the list.
|
1234 |
if (isset($links['export'])) { |
1235 |
$links = array('export' => $links['export']) + $links; |
1236 |
} |
1237 |
} |
1238 |
|
1239 |
/**
|
1240 |
* Allows altering the commands which are used on a views AJAX request.
|
1241 |
*
|
1242 |
* @param array $commands
|
1243 |
* An array of ajax commands.
|
1244 |
* @param object $view
|
1245 |
* The view which is requested.
|
1246 |
*/
|
1247 |
function hook_views_ajax_data_alter(&$commands, $view) { |
1248 |
// Replace Views' method for scrolling to the top of the element with your
|
1249 |
// custom scrolling method.
|
1250 |
foreach ($commands as &$command) { |
1251 |
if ($command['command'] == 'viewsScrollTop') { |
1252 |
$command['command'] .= 'myScrollTop'; |
1253 |
} |
1254 |
} |
1255 |
} |
1256 |
|
1257 |
/**
|
1258 |
* Allow modules to respond to the Views cache being invalidated.
|
1259 |
*
|
1260 |
* This hook should fire whenever a view is enabled, disabled, created,
|
1261 |
* updated, or deleted.
|
1262 |
*
|
1263 |
* @param string $cid
|
1264 |
* The cache identifier that is being cleared.
|
1265 |
*
|
1266 |
* @see views_invalidate_cache()
|
1267 |
*/
|
1268 |
function hook_views_invalidate_cache($cid) { |
1269 |
cache_clear_all('views:*', 'cache_mymodule', TRUE); |
1270 |
} |
1271 |
|
1272 |
/**
|
1273 |
* Allow modules to alter a view prior to being saved.
|
1274 |
*/
|
1275 |
function hook_views_view_presave($view) { |
1276 |
// Do some adjustments to the view. Handle with care.
|
1277 |
if (mymodule_check_view($view)) { |
1278 |
mymodule_do_some_voodoo($view);
|
1279 |
} |
1280 |
} |
1281 |
|
1282 |
/**
|
1283 |
* Allow modules to respond to a view being saved.
|
1284 |
*/
|
1285 |
function hook_views_view_save($view) { |
1286 |
// Make a watchdog entry.
|
1287 |
watchdog('views', 'The view @name was deleted by @user at @time', array('@name' => $view->name, '@user' => $GLOBALS['user']->name, '@time' => format_date(time()))); |
1288 |
} |
1289 |
|
1290 |
/**
|
1291 |
* Allow modules to respond to a view being deleted or reverted.
|
1292 |
*/
|
1293 |
function hook_views_view_delete($view) { |
1294 |
// Make a watchdog entry.
|
1295 |
watchdog('views', 'The view @name was deleted by @user at @time', array('@name' => $view->name, '@user' => $GLOBALS['user']->name, '@time' => format_date(time()))); |
1296 |
} |
1297 |
|
1298 |
/**
|
1299 |
* @}
|
1300 |
*/
|
1301 |
|
1302 |
/**
|
1303 |
* @defgroup views_module_handlers Views module handlers
|
1304 |
* @{
|
1305 |
* Handlers exposed by various modules to Views.
|
1306 |
* @}
|
1307 |
*/
|