Charts API

Moodle 3.2

Overview

On the roadmap for Moodle 3.2 was added the requirement for a new charting library.

Requirements

The requirements can be split in two different categories, the rendering, and the API.

Rendering

The rendering of the charts must occur on the client-side, in Javascript. It must be visually pleasing without the need for a lot of customisation. It has to be accessible, support translation and right-to-left languages. It must reasonably support large datasets and dynamic data changes, for instance when fetching and including more data from an Ajax request. The charts generated can be printed. Aside the feature requiremements, the library itself has to be mature, stable and under active development. Its popularity on networks such as Github and Stackoverflow is a good indicator. It must also be downloadable to be shipped and served locally from Moodle.

The API

Simplicity is the main keyword here. Programmatically creating a new chart must be as simple as possible. The API has to be designed so that using a different rendering engine later on is possible (when switching to another library). The API must be available from both PHP and Javascript, so that a chart can be created from any of these even if its rendering will happen solely in Javascript.

The winner is

Chart.js wins We have investigated the following libraries: Chart.js Highcharts CanvasJS Chartist n3 Google Charts Flot/jQuery D3 Plotly.js/D3 C3/D3 nvd3/D3 dimple-js/D3 dc-js/D3 metricsgraphicsjs/D3 ECharts After considering popularity (Github stars, contributors, Stackoverflow questions), license, maturity, and relative simplicity, we shortlisted these: C3 Chart.js Echarts Chart.js won because it is the most popular even though it only contains a limited set of chart types. Echarts was very promising but the community around it being mainly non-English speaking felt risky as getting help online would be much harder. C3 is a layer on top of D3 with aim to provide a simpler charting solution, however its popularity was quite limited compared to the other ones. Other more or less popular libraries could have been discarded because of their license, complexity, or being an overkill for what we need.

The API

Just as the requirements, the API was split in two different categories, the chart structure, and the rendering. Data structure In order to create a library agnostic to the rendering mechanism used, the API must construct a data structure representing the chart. Not only it needs to contain the data to be displayed, but also some information on the display itself, such as the type of chart, the axis labels, etc... The goal of the data structure is not to contain all the rendering options offered by the multitude of charting libraries out there, it is simply to advise the rendering method on how the data should be presented. As much as possible the options have to remain simple. For example the data structure will not contain a parameter determining the thickness of the lines in a chart, that is the sole responsibility of the rendering engine. The API to construct the data structure of a chart is available in both PHP and Javascript, however it is acceptable for the validation of the data to only occur in Javascript. This to avoid duplicating too much code, especially as Javascript is always invoked for rendering purposes. The PHP objects of the API implement the built-in interface jsonSerializable. The serialisation will be the mechanism used to export a PHP-made structure to Javascript as a JSON object. Only PHP needs to support the serialisation. The Javascript API implements the mechanism to restore a chart structure from JSON data. Whilst limiting, it is important to not oversee the benefits of this data structure. It creates a self-documenting API exposing the different attributes and methods a data structure supports. It streamlines the data visualisation to its essential components, offering a quick and easy way to implement new charts to developers without the need for a knowledge of the rendering library. And it allows for a chart structure to be exported to any Moodle frontend such as the Web interface, but also the mobile app.

Rendering

This part of the API only happens in Javascript. The rendering engine receives the data structure and converts it to a visualisation of this data. Mainly this will translate the data structure into the format expected by existing charting libraries and output the result. This allows for an instant migration to another charting library, simply by replacing the rendering engine, and for custom rendering engines such as outputting the chart data to a table for accessibility purposes. The engine can be notified that the chart data structure has changed and that the output needs to be updated. Moodle will ship with an output engine for Chart.js and another one to generate HTML tables.