Configure Charts

This guide details how to configure charts. You will learn how to provide data for a chart and display this data in the required way. In addition, you will learn how to customize the default chart appearance to your requirements. As a result, you will get a chart that shows how the population has been growing on each continent in the last sixty years. Separately, you will add a pie chart that shows the population distribution between continents by 2010.

You can watch video lessons on ChartJS widgets. Here are the videos that will allow you to get started with charts: ChartJS: Getting Started with dxChart and ChartJS: Getting Started with dxPieChart.

Create a Chart

Begin by creating an HTML file. Then, add references to the required libraries (see the Add Libraries tutorial).

HTML
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <script type="text/javascript" src="jquery-1.9.1.min.js"></script>
        <script type="text/javascript" src="knockout-2.2.1.js"></script>
        <script type="text/javascript" src="globalize.min.js"></script>
        <script type="text/javascript" src="dx.chartjs.js"></script>
    </head>
    <body></body>
</html>

There are several approaches to creating a ChartJS widget. This page will utilize the jQuery approach. Refer to the Add a Widget tutorial to go over the other approaches.

Add a div element. It will be a container for the dxChart widget.

HTML
<body>
    <div id="chartContainer" style="max-width:700px;height: 300px;"></div>
</body>

Create the dxChart widget within the added container.

HTML
<head>
    <!-- ... -->
    <script type="text/javascript">
        $(function () {
            $("#chartContainer").dxChart({});
        })
    </script>
</head>

Run this code and you will see an empty dxChart widget, in which data must now be specified.

Provide Data

The data that we will use will be taken from the http://www.geohive.com resource.

To define the data source to be used for Chart series, assign an array of objects to the dataSource property of the chart's configuration object.

JavaScript
var chartDataSource = [
    {
        year: 1950, Africa: 227, Americas: 331,
        Asia: 1436, Europe: 547, Oceania: 12
    },
    {
        year: 1960, Africa: 285, Americas: 416,
        Asia: 1718, Europe: 605, Oceania: 15
    },
    {
        year: 1970, Africa: 365, Americas: 512,
        Asia: 2156, Europe: 657, Oceania: 19
    },
    {
        year: 1980, Africa: 478, Americas: 612,
        Asia: 2644, Europe: 695, Oceania: 22
    },
    {
        year: 1990, Africa: 633, Americas: 720,
        Asia: 3180, Europe: 722, Oceania: 26
    },
    {
        year: 2000, Africa: 810, Americas: 833,
        Asia: 3678, Europe: 731, Oceania: 30
    },
    {
        year: 2010, Africa: 1016, Americas: 936,
        Asia: 4149, Europe: 728, Oceania: 35
    }
];
$(function () {             
    $("#chartContainer").dxChart({
        dataSource: chartDataSource,
    });
});

Now, let's define chart series using data from the assigned data source. For this purpose, we will use the following series properties.

  • name
    Used to identify a series in the legend.
  • argumentField
    Specifies the field in the data source that provides arguments for series points.
  • valueField
    Specifies the field in the data source that provides values for series points.

The following code shows these properties in use.

JavaScript
$("#chartContainer").dxChart({
    dataSource: chartDataSource,
    commonSeriesSettings: {
        argumentField: 'year'
    },
    series: [{
        name: 'Oceania',            
        valueField: 'Oceania'
    }, {
        name: 'Africa',
        valueField: 'Africa'
    },{
        name: 'Americas',
        valueField: 'Americas'
    },{
        name: 'Asia',
        valueField: 'Asia'
    },{ 
        name: 'Europe',
        valueField: 'Europe'
    }]
});

As you can see in the code above, we can use the commonSeriesSettings object to specify the options that are common for all series in the chart.

As you noticed, we have not specified a series type for our data. The 'line' series type is used by default.

Set a Series Type

Now, let's change the series type from the default 'line' type to the fullStackedArea type, as the latter is more appropriate when you want to compare point values and their aggregate for the same point arguments.

Generally, you can specify a series type for individual series using their type option. But in our example, we will set the 'fullStackedArea' series type for all series. To do this, we will use the type property of the commonSeriesSettings configuration object.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        //...
        type: 'fullStackedArea'
    }
    //...
});

Show Point Labels

By default, area type series are displayed without points and labels. Let's leave points invisible but display labels for them.

To specify whether or not to show labels for all chart points, define the label object within the commonSeriesSettings configuration object.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        label: {
            visible: true,
            connector: {
                visible: true
            }
        }
        //...
    }
    //...
});

If you want to display labels for a particular series only, define the label object within the corresponding series object in the series array.

Enable Tooltips

Now, enable tooltips for series points. This will allow you to see the percent value of any point. To enable tooltips, use the tooltip configuration object, as shown below.

JavaScript
$("#chartContainer").dxChart({
    tooltip: {
        enabled: true
    }
    //...
});

Tooltips display the value of the point that is currently hovered over. To display the percentage of the point's value, introduce the customizeText function for tooltips as shown in the code below.

JavaScript
$("#chartContainer").dxChart({
    tooltip: {
        enabled: true,
        percentPrecision: 2,
        customizeText: function(value){
            return value.percentText;
        }
    }
    //...
});

Title and Legend

The last thing that we need to do for our chart is to display a title and relocate the legend to the bottom.

To set a title, use the title configuration object.

JavaScript
$("#chartContainer").dxChart({
    title: {
        text: 'Continental Population Shift (in millions)'
    }
    //...
});

To relocate the legend from its default place, use the legend configuration object.

JavaScript
$("#chartContainer").dxChart({
    legend: {
        horizontalAlignment: 'center',
        verticalAlignment: 'bottom'
    },
    //...
});

The configured chart now meets our requirements. Next, let's take a look at the dxPieChart widget, which is described further.

Add a Pie Chart

To display information on a pie chart, use the dxPieChart widget supplied with the ChartJS library. This page will guide you through configuring this widget to your requirements. As a result, you will get a pie chart that demonstrates the population distribution between continents by 2010. We will get data from the http://www.geohive.com resource.

Like all the widgets from the ChartJS library, the dxPieChart widget can be created using either the JQuery or Knockout approach. Both of them are detailed in the Add a Widget tutorial.

To provide data for the dxPieChart widget, set a data source and specify the argument and value fields for a series, as we did for the dxChart widget in the previous steps.

HTML
<div id="pieChartContainer" style="max-width:800px;height: 400px;"></div>
JavaScript
var pieChartDataSource = [
    {category: 'Oceania', value: 35},
    {category: 'Africa', value: 1016},
    {category: 'Americas', value: 936},
    {category: 'Asia', value: 4149},
    {category: 'Europe', value: 728}                                                        
];

$(function () {             
    $("#pieChartContainer").dxPieChart({
        dataSource: pieChartDataSource,
        series: {
            argumentField: 'category',
            valueField: 'value',
        }    
    });
});

Now, let's enable tooltips, labels, specify a title and relocate the legend, as we did for the dxChart widget earlier.

JavaScript
$("#pieChartContainer").dxPieChart({
    series: {
        //...
        label: {
            visible: true,
            connector: {
                visible: true
            }
        }
    },
    tooltip: {
        enabled: true,
        percentPrecision: 2,
        customizeText: function (value) {
            return value.percentText;
        }
    },
    title: {
        text: 'Continental Population by 2010 (in millions)'
    },
    legend: {
        horizontalAlignment: 'center',
        verticalAlignment: 'bottom'
    }
    //...
});

As you can see, the dxPieChart and dxChart widgets have much in common. The only difference is that the dxPieChart widget has a single series.