INTRODUCTION

govCMS CKAN provides integration with CKAN (http://ckan.org/). CKAN is a powerful data management system that makes data accessible by providing tools to streamline publishing, sharing, finding and using data.

Authors

This module was created by Jeremy Graham @ Doghouse Agency for GovCMS with assistance and guidance from Acquia and these contributors.

Submodules

govCMS CKAN Display

Handles turning the tabular data into charts.
Provides ability to download charts as svg/png.
Provides visualisation plugins for common formats (eg. Bar, spline, line)

govCMS CKAN Display Examples

Provides an examples page for viewing different chart types.

govCMS CKAN Media

Provides media internet integration.
Provides a CKAN file type and stream wrapper/handler.
Visualisation configuration field/widget.
Visualisation formatter/renderer.

GovCmsCkanClient Class

This client class handles fetching, caching and returning data from a CKAN endpoint.

The CKAN base URL and API key are configured via the admin UI. When an endpoint request is made it will first check if there is a local cached version and if not expired, will return that. If no cache exists or expired a new request to the endpoint is performed and cached.

Basic Usage of the class:

// Get a new instance of the class.
$client = govcms_ckan_client();

// Make a request.
$resource = 'action/package_show';
$query_params = array('id' => '1234');
$client->get($resource, $query_params);

This will make a request to the api which will look similar to this: http://my.ckan.enpoint.baseurl/api/3/action/package_show?id=1234

Valid responses:

The response object should always contain a valid property to indicate if the data returned is valid/usable. If FALSE there was either an error in the http request or possibly the CKAN request. All failed requests will get added to watchdog.

Examples of resources: action/package_show - metadata for a resource action/datastore_search - records (data) for a resource

Wrappers/Helpers:

// Return a resource metadata.
$meta = govcms_ckan_client_request_meta($resource_id);

// Return the records for a resource.
$records = govcms_ckan_client_request_records($resource_id);

GovCmsCkanDatasetParser Class

This parser class handles parsing the response records from the client class into table(s).

The parsed output is in a format for handing straight to theme_table either directly or by using a renderable array. Data can be represented in multiple ways, and this class provides setters to control how the data/table will be presented.

Basic usage of the class:

// Get a new instance of the class.
$parser = govcms_ckan_dataset_parser();

// Set the options.
$parser
  ->setResult($response_data)
  ->setKeys($keys)
  ->setLabelKey($label_key)
  ->setHeaderSource($x_axis_grouping)
  ->setTableAttributes($attributes)
  ->setGroupKey($group_key);
  ->parse();

GovCmsCkanDatasetParser.inc is well documented, see comments for what each setter does. You can also look at some of the visualisations used in govcms_ckan_display for working examples.

Visualisation plugins

Visualisations are cTools plugins, a module must implement the following for plugins to be registered:

function hook_ctools_plugin_directory($module, $plugin) {
  if ($module == 'govcms_ckan' && in_array($plugin, array_keys(govcms_ckan_ctools_plugin_type()))) {
    return 'plugins/' . $plugin;
  }
}

Visualisation plugins should live in the plugins/visualisations folder.

The best place to start with creating a new visualisation is by copying a visualisation from govcms_ckan_display/plugins/visualisation to your own module/theme and the customise.

Each plugin file should contain the following structure:

$plugin = array(
  'title' => 'My visualisation title',
  'settings' => array(),
);
function MODULE_NAME_PLUGIN_NAME_view($file, $display, $config){
  // Return renderable array of visualisation.
}
function MODULE_NAME_PLUGIN_NAME_configure($plugin, $form, $form_state, $config){
  // Return form structure array for configuration elements.
}

Configuration helpers:

There is a few helpers that include common structure/elements for visualisation configure forms. The intention is a plugin configuration form will include these as required.

  // Include default widgets.
  $widgets = array(
    'govcms_ckan_media_visualisation_default_key_config',
    'govcms_ckan_media_visualisation_default_axis_config',
    'govcms_ckan_media_visualisation_default_grid_config',
    'govcms_ckan_media_visualisation_default_chart_config',
  );
  $config_form = govcms_ckan_media_visualisation_include_form_widgets($form, $form_state, $config, $widgets);

Adding custom stlyes to exported charts

Exported charts (Download as PNG/SVG) must have the css embedded in the SVG, as you may want to add additional styling to the exported files, govcms_ckan_display provides a way for you add your own external stylesheets that get embedded for export. Example:

  drupal_add_js(array(
    'govcmsCkanDisplay' => array(
      'exportStylesheets' => array(url('path/to/custom/css/graph_export.css')),
    ),
  ), 'setting');

NOTE: This requires jQuery 1.5+