@data-fair/app-charts

A simple charting application for DataFair. Also used as an example for the documentation.

It is hosted by npm and the jsdelivr CDN.

An example app can be found here, it uses this dataset.

Context

DataFair is an Open Source Web software developped by Koumoul for publishing data online with complete search and aggregation capabilities, metadata management, mapping functionalities, access control, etc. It can be used as a back office for Open Data platforms, data visualizations, custom search engines and other applications.

DataFair comes with functionalities to facilitate the development, deployment and configuration of small data consuming applications. app-charts is an example of such an application.

Technical stack

This technical stack is just an example of what can be used to build an application for DataFair. It is a quite rich stack for a state of the art development environment. For an application with a more minimalist stack, you can see app-minimal. For a state of the art application generator see the vue-cli plugin.

• vuejs: our favorite framework for client-side code
• vuetify: a material design UI framework for vuejs
• chartjs: simple charting library

Development Setup

Start by downloading, cloning or forking this repository:

git clone https://github.com/data-fair/app-charts.git
cd app-charts

Install nodejs dependencies for the development environment:

npm install

If you are running a local data-fair instance

Create a dataset in your data-fair instance. You can use this public dataset for example.

Run the development server and serve the application with hot reload here:

npm run dev-src

You can now add an application configuration pointing to http://localhost:3000 in your data-fair instance. Edit the configuration, edit the source code, etc.

Else

Run the development server and serve the application with hot reload here:

npm run dev

You will find a dev server running at http://localhost:5888. It contains sample data and a sample configuration. You can edit the source code, edit the configuration, etc.

DataFair application specificity

A DataFair application is mostly like any Web application. You can consume DataFair APIs from any framework for example. But for a seamless integration and multi-configuration management by DataFair you need to respect a few conventions. The following sections are a focus on the files that implement these conventions.

public/config-schema.json

A JSON schema file that describes the expected configuration. DataFair expects this file to be found at the precise path %MY_APP%/config-schema.json.

The content of this JSON schema is extended with some annotations used by DataFair to automatically create a configuration form. The details of these annotations can be found in demo of the library we maintain to create these forms: vuetify-jsonschema-form.

index.html

This the root template used to generate the HTML pages of this application. The key element here is this line:

<script type="text/javascript">window.APPLICATION=%APPLICATION%;</script>

The string %APPLICATION% will be replaced automatically by the actual content of the configuration, when this application is re-exposed by DataFair. Later code can use the global variable APPLICATION (window.APPLICATION) to start interacting with the DataFair API.
The important part for DataFair is the presence of the meta properties "title" and "description".

Deployment

To publish the project, upload it to the global npm registry (you need to be a member of the owner organization).

npm version PATCH|MINOR|MAJOR
npm publish
git push && git push --tags

If the release is a bug fix and you don't want to wait 24h (the cache delay of jsdelivr), you can purge the cache for the index.html file of the minor version in the CDN:

curl https://purge.jsdelivr.net/npm/@data-fair/app-charts@VER/dist/index.html

Replace VER with the minor version number (e.g. 1.0).

To publish a version for testing purposes you can tag it as a pre-release and publish it with the tag "staging".

npm version prerelease --preid=staging
npm publish --tag staging
curl https://purge.jsdelivr.net/npm/@data-fair/app-charts@staging/dist/index.html
git push && git push --tags