views.api.php

You are here

Describe hooks provided by the Views module.

Functions

Namesort descending Description
hook_field_views_data Override the default data for a Field API field.
hook_field_views_data_alter Alter the views data for a single Field API field.
hook_field_views_data_views_data_alter Alter the views data on a per field basis.
hook_views_ajax_data_alter This hook allows to alter the commands which are used on a views ajax request.
hook_views_api Register View API information.
hook_views_data Describes data tables (or the equivalent) to Views.
hook_views_data_alter Alter table structure.
hook_views_default_views This hook allows modules to provide their own views which can either be used as-is or as a "starter" for users to build from.
hook_views_default_views_alter Alter default views defined by other modules.
hook_views_form_substitutions This hook is called to get a list of placeholders and their substitutions, used when preprocessing a View with form elements.
hook_views_invalidate_cache Allow modules to respond to the Views cache being invalidated.
hook_views_plugins Describes plugins defined by the module.
hook_views_plugins_alter Alter existing plugins data, defined by modules.
hook_views_post_build This hook is called right after the build process. The query is now fully built, but it has not yet been run through db_rewrite_sql.
hook_views_post_execute This hook is called right after the execute process. The query has been executed, but the pre_render() phase has not yet happened for handlers.
hook_views_post_render Post process any rendered data.
hook_views_preview_info_alter Alter the information box that (optionally) appears with a view preview, including query and performance statistics.
hook_views_pre_build This hook is called right before the build process, but after displays are attached and the display performs its pre_execute phase.
hook_views_pre_execute This hook is called right before the execute process. The query is now fully built, but it has not yet been run through db_rewrite_sql.
hook_views_pre_render This hook is called right before the render process. The query has been executed, and the pre_render() phase has already happened for handlers, so all data should be available.
hook_views_pre_view Allows altering a view at the very beginning of views processing, before anything is done.
hook_views_query_alter Alter the query before executing the query.
hook_views_query_substitutions Performs replacements in the query before being performed.
hook_views_ui_display_top_links_alter This hooks allows to alter the links at the top of the view edit form. Some modules might want to add links there.

File

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