Graphs and Charts

The forms designer includes two fields that can be used to draw graphs and charts. The fields are implementations of the popular JavaScript libraries, DimpleJS (opens new window) and D3.js (opens new window), each of which have their own full API documentation.

The focus of this article is on DimpleJS, which provides a wrapper around D3 that can be used for most chart and graph based visualisations.

Data

The data supplied to your Dimple chart should be an array of JSON objects with consistent property names. Nested objects are not supported. This data can be returned from calls to API Server Workers and End Points, or taken from fields on your form.

Whatever the source of your data, it should be set as the value of your chart field. This provides you with three options:

• Setting a fixed value for the chart using the field's Default property
• Using the field's Default Function to fetch the data from another source as the field loads
• Using the helper library's helper.setFieldValue(fieldName, value) function to pass the value of another field or variable to the chart field

Example Data Structure

This data includes the names and ages of various people, ready to be plotted on a Dimple bar chart:

[{   
    "Name": "Tim",
    "Age": 35
}, {   
    "Name": "Leo",
    "Age": 34
}, {   
    "Name": "Bill",
    "Age": 33
}, {    
    "Name": "George",
    "Age": 28
}]

This data set would suit a double line chart, with a line for each person, pizza toppings on the x-axis, and a count on the y-axis:

[{
    "Person": "Janet",
    "Topping": "Mushrooms",
    "Amount": 5
}, {
    "Person": "Janet",
    "Topping": "Courgette",
    "Amount": 2
}, {
    "Person": "Janet",
    "Topping": "Pepperoni",
    "Amount": 8
}, {
    "Person": "John",
    "Topping": "Mushrooms",
    "Amount": 7
}, {
    "Person": "John",
    "Topping": "Courgette",
    "Amount": 6
}, {
    "Person": "John",
    "Topping": "Pepperoni",
    "Amount": 2
}]

Defining the Chart

The Dimple field's Script Function is where you write the JavaScript that will turn your data into a chart. It is here you can manipulate the data, set up the axis, decide which data will be plotted, and use the full DimpleJS (opens new window) API to customise how your chart appears.

This script would plot the Name/Age data above as a bar chart:

helper.registerCustomFieldFn("CHART","initChart",function(chart){
    chart.addCategoryAxis("x", "Name");
    chart.addMeasureAxis("y", "Age");
    chart.addSeries(null, dimple.plot.bar);
});

Different charts and styles are explored in the example forms related to this page.

Drawing the Chart

Once your data has been passed to the Dimple chart, the field's custom function, drawChart, should be invoked - helper.invokeCustomFieldFn('chartFieldName', 'drawChart');

This can be done with the request that sets the value of the chart:

function(helper) {
    var item;
    item = [{
        Name: 'Tim',
        Presents: helper.getFieldValue('TIMSCHRISTMASPRESENTS')
    }, {
        Name: 'Leo',
        Presents: helper.getFieldValue('LEOSCHRISTMASPRESENTS')
    }];
    helper.setFieldValue('CHART', item);
    helper.invokeCustomFieldFn('CHART', 'drawChart');
}

Or added to the chart's Handler Function, invoking it's own drawChart custom function whenever its value changes:

function(helper, fieldName, value, valid, eventName) {
    if (eventName == 'CHANGE' && valid) {
        helper.invokeCustomFieldFn('CHART', 'drawChart');
    }
}