Drupal Views: Extending Contextual Filters and Basic Plugin Design

Overview
I am in the midst of coding a large variety of widgets to enhance Drupal’s ability to handle large quantities of geospatial and numerical data.  In doing so, one project is to allow Views Contextual Filters to support standard comparators like >, <, >=, etc. for integer and floating point fields/columns/properties (Contextual Filters are WHERE clause parameters submitted via URL arguments).  In the process of doing so, I am using another Views plugin, Views GeoJSON, as a template and documenting it’s approach here.

Structure and Function of Views GeoJSON
The Views GeoJSON module:

  1. Gives Views the ability to render a set of Views query data in a GeoJSON format.
  2. Gives Views the ability to accept a “bounding box” as an argument and implement a geospatial WHERE clause based on this bounding box.

The module is implemented in the following directory/files and functions:

  • views/plugins/views_geojson/
    • ./views_geojson.info – basic info
    • ./views_geojson.module – hook_views_api(), hook_ctools_plugin_api(), and 2 local functions to do the actual data: _views_geojson_render_fields() & _views_geojson_encode_formatted()
    • ./views/ – folder broadcast to Views by the function “views_geojson_views_api()”
      • views_geojson_bbox_argument.inc, provides the following:
        • class views_geojson_bbox_argument – extension of views_handler_argument – this is where the argument function alters the Views query
      • views_plugin_argument_default_bboxquery.inc –  a special argument handler to provide the default value when the argument is not present in the URL (class “views_plugin_argument_default_bboxquery” defined in it’s own file
      • views_plugin_style_geojson.inc – defines all the Views output style configuration information options shown in “Views -> Format -> GeoJSON Feed -> Settings”.
      • views_geojson.views.inc (NOT included in views_geojson.inc), has hooks:
        • hook_views_plugins() – tells Views about this modules output style (including the title info shown in “Views -> Format” dialog), the directory (but not actual file name) of the Template file, and the presence of the default argument handler (“views_plugin_argument_default_bboxquery” decribed above).
        • hook_views_handlers() – tells Views what handlers this module exposes (class “views_geojson_bbox_argument”), and where to find the file to include
        • hook_views_data() – provides the info that adds this filter to the list of options in the “Contextual Filters – Add” dialog, and tells Views that the class “views_geojson_bbox_argument” will define the views_handler_argument for it.
      • views-views-geojson-style.tpl.php (NOT included in views_geojson.inc)

Of note are “hooks”, and also files that are indicated above as “NOT included” in the modules .info file.  Files that are NOT included in the .info file are either: a) included somewhere else, or b) auto-magically included because of their naming convention.  For example, the views_geojson_views_api() function tells views that this plugin exists and where to find the things that a Views plugin uses – this support and path is what tells Views that it will look in the “.views/” path and find the files “views_geojson.views.inc” and “views-views-geojson-style.tpl.php” that were not explicitly included.  This module also has the hook “views_geojson_ctools_plugin_api”, which says that it is capable of receiving plugins of it’s own, and if they were to exist they appear in a sub-directory called “includes”, however, this is just a stub as no “includes” directory currently exists in this version of the views_geojson module.

Contextual Filter Details
The contextual filter is imjplemented in 2 files “views_geojson.views.inc” and “views_geojson_bbox_argument.inc”, with a 3rd file “views_plugin_argument_default_bboxquery.inc” implementing the default for the filter (I think this default plugin may be optional?). The .module file annouces support for the Views API, which makes tells Views that it should look for the file “views_geojson.views.inc”, but other than that it does not actually contribute anything to the Contextual Filter execution.  The .info file, while necessary of course, simply makes the appropriate includes to tell Views about the 2 files that do the heavy lifting.

Parting Thoughts
The Views GeoJSON module provides a nice example of both a Views plugin, as well as good standard Drupal 7 coding practices: a convention-based file structure, employing hooks, and the use of a modules API’s when trying to extend it.

References:

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s