- 1.16.x modules/views/views.api.php views_plugins
- 1.17.x modules/views/views.api.php views_plugins
- 1.18.x modules/views/views.api.php views_plugins
In Views, a plugin is a bit like a handler, but plugins are not directly responsible for building the query. Instead, they are objects that are used to display the view or make other modifications.
There are several types of plugins in Views:
- Display: Display plugins are responsible for controlling *where* a view lives; that is, how they are being exposed to other parts of Backdrop. Page and block are the most common displays, as well as the ubiquitous 'master' (or 'default') display.
- Style: Style plugins control how a view is displayed. For the most part they are object wrappers around theme templates. Styles could for example be HTML lists or tables.
- Row style: Row styles handle each individual record from the main view table. The two included by default render the entire entity (nodes only), or selected fields.
- Argument default: Argument default plugins allow pluggable ways of providing default values for contextual filters (previously 'arguments'). This is useful for blocks and other display types lacking a natural argument input. Examples are plugins to extract node and user IDs from the URL.
- Argument validator: Validator plugins can ensure arguments are valid, and even do transformations on the arguments. They can also provide replacement patterns for the view title. For example, the 'content' validator verifies that the argument value corresponds to a node, loads that node and provides the node title as a replacement pattern.
- Access: Access plugins are responsible for controlling access to the view. Views includes plugins for checking user roles and individual permissions.
- Query: Query plugins generate and execute a query, so they can be seen as a data backend. The default implementation is using SQL. There are contributed modules reading data from other sources, see for example the Views XML Backend module.
- Cache: Cache plugins control the storage and loading of caches. Currently they can do both result and render caching, but maybe one day cache the generated query.
- Pager plugins: Pager plugins take care of everything regarding pagers. From getting and setting the total amount of items to render the pager and setting the global pager arrays.
- Exposed form plugins: Exposed form plugins are responsible for building, rendering and controlling exposed forms. They can expose new parts of the view to the user and more.
- Display extenders: Display extender plugins allow scaling of views options horizontally. This means that you can add options and do stuff on all views displays. One theoretical example is metatags for views.
Plugins are registered by implementing hook_views_plugins() in your modulename.views.inc file and returning an array of data. For examples please look at views_views_plugins() in views/includes/plugins.inc as it has examples for all of them.
Similar to handlers, make sure that you add your plugin files to the module.info file.
The array defining plugins will look something like this:
return array( 'display' => array( // ... list of display plugins, ), 'style' => array( // ... list of style plugins, ), 'row' => array( // ... list of row style plugins, ), 'argument default' => array( // ... list of argument default plugins, ), 'argument validator' => array( // ... list of argument validator plugins, ), 'access' => array( // ... list of access plugins, ), 'query' => array( // ... list of query plugins, ), 'cache' => array( // ... list of cache plugins, ), 'pager' => array( // ... list of pager plugins, ), 'exposed_form' => array( // ... list of exposed_form plugins, ), 'display_extender' => array( // ... list of display extender plugins, ), );
Each plugin will be registered with an identifier for the plugin, plus a fairly lengthy list of items that can define how and where the plugin is used. Here is an example of a row style plugin from Views core:
'node' => array( 'title' => t('Node'), 'help' => t('Display the node with standard node view.'), 'handler' => 'views_plugin_row_node_view', 'path' => backdrop_get_path('module', 'views') . '/modules/node', // not necessary for most modules 'theme' => 'views_view_row_node', 'base' => array('node'), // only works with 'node' as base. 'uses options' => TRUE, 'type' => 'normal', ),
Of particular interest is the *path* directive, which works a little differently from handler registration; each plugin must define its own path, rather than relying on a global info for the paths. For example:
'feed' => array( 'title' => t('Feed'), 'help' => t('Display the view as a feed, such as an RSS feed.'), 'handler' => 'views_plugin_display_feed', 'uses hook menu' => TRUE, 'use ajax' => FALSE, 'use pager' => FALSE, 'accept attachments' => FALSE, 'admin' => t('Feed'), 'help topic' => 'display-feed', ),
Please be sure to prefix your plugin identifiers with your module name to ensure namespace safety; after all, two different modules could try to implement the 'grid2' plugin, and that would cause one plugin to completely fail.
@todo Finish this document.
views/ views.api.php, line 135
- Describe hooks provided by the Views module.