ckanext-graph

A CKAN extension that adds a graph view for resources.

Overview

Adds graph views for resources on a CKAN instance. Two types of graph are available: temporal (a line graph showing count over time based on a specified date field), and categorical (a bar chart showing counts for various values in a specified field).

NB: the current version of this extension only works with the Natural History Museum's ElasticSearch datastore CKAN backend. However, it is designed to be extensible, so if you would like to use this extension with a different backend (e.g. the standard PostgreSQL datastore), please see the Extending section.

Installation

Path variables used below: - $INSTALL_FOLDER (i.e. where CKAN is installed), e.g. /usr/lib/ckan/default - $CONFIG_FILE, e.g. /etc/ckan/default/development.ini

Installing from PyPI

shell pip install ckanext-graph

Installing from source

1. Clone the repository into the src folder: shell cd $INSTALL_FOLDER/src git clone https://github.com/NaturalHistoryMuseum/ckanext-graph.git

2. Activate the virtual env: shell . $INSTALL_FOLDER/bin/activate

3. Install via pip: shell pip install $INSTALL_FOLDER/src/ckanext-graph

Installing in editable mode

Installing from a pyproject.toml in editable mode (i.e. pip install -e) requires setuptools>=64; however, CKAN 2.9 requires setuptools==44.1.0. See our CKAN fork for a version of v2.9 that uses an updated setuptools if this functionality is something you need.

Post-install setup

1. Add 'graph' to the list of plugins in your $CONFIG_FILE: ini ckan.plugins = ... graph

2. Install lessc globally: shell npm install -g "less@~4.1"

Configuration

These are the options that can be specified in your .ini config file.

| Name | Description | Options | Default | |-------------------------|--------------------------------------------------------------------------------|--------------------|---------------| | ckanext.graph.backend | The name of the backend to use (currently only elasticsearch is implemented) | elasticsearch, sql | elasticsearch |

Usage

Templates

The view will be added as an option with no further configuration necessary. However, if you wish to override or add content to the template, you can extend templates/graph/view.html:

```html+jinja {% ckan_extends %}

{% block mynewblock %}

Look, some exciting new content.

Extending

To use this extension with a datastore backend other than the ElasticSearch backend already implemented, you'll have to subclass from Query in ckanext-graph/ckanext/graph/db.py.

An unimplemented class for SQL queries is already in the file as an example:

```python class SqlQuery(Query): @property def datequery(self): raise NotImplementedError()

@property
def _count_query(self):
    raise NotImplementedError()

def run(self):
    raise NotImplementedError()

```

If you add a new class, you'll have to add it to the dictionary in Query.new() method to make it available as a configurable option.

If you do this, please submit a pull request! Contributions are always welcome.

Testing

There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the docker/ folder.

To run the tests against ckan 2.9.x on Python3:

1. Build the required images: shell docker compose build

2. Then run the tests. The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies. shell docker compose run ckan