Data Binding

To draw a chart, provide data for the Chart's series. To do this, use one of the following approaches, no matter which series types you are going to use.

Use the approach that is more appropriate for your task.

Based on the type of the provided data, continuous or discrete axes will be generated. Their ticks/grid line will be arranged automatically. However, you can change the axis type, customize the default tick arrangement and label formatting. For details, refer to the Axes and Data Formatting help sections.

Use Common Data Source

To specify data for the dxChart widget, you can use a common data source for all the series to be displayed on the chart. The data source must represent an array of objects, each of which specifies series values for a particular argument. In this topic, you will see how the data array should be introduced.

Let the following variable be a data source to be assigned to a chart.

JavaScript
var commonDataSource = [
    { month: 'January', Glendale: 58, Kirkland: 42 },
    { month: 'February', Glendale: 59, Kirkland: 44 },
    //...
    { month: 'December', Glendale: 58, Kirkland: 41 },
];

As you can see in the code above, two series ("Glendale" and "Kirkland") are prepared to be visualized and the argument axis is going to be discrete ("month" categories).

There are series types in which there are more than one value per argument, e.g. a candleStick, stock, rangeArea and rangeBar series types. In this instance, all the values must be listed in the data source's objects. The following code demonstrates how a data source can be defined when a series of the rangebar type is going to be used:

JavaScript
var dataSource = [
    { month: 'January', min1: 36, max1: 43.29, min2:  42.12, max2: 49.91 },
    { month: 'February', min1: 40.68, max1: 47.07, min2: 28.33, max2: 51.75 },
    //...
    { month: 'December', min1: 55.22, max1: 59.22, min2: 57.34, max2: 61.37},
];

To set a common data source to a chart, use the dataSource configuration object as demonstrated in the code below.

JavaScript
$("#chartContainer").dxChart({
    dataSource: commonDataSource,
    //...
});

Now, we can use the provided data source when defining the chart's series. For this purpose, fields for values and arguments must be specified. Refer to the following topics for details:

Argument and value axes are generated automatically based on the data provided in the data source. To learn how to specify whether an axis must be continuous or discrete, and how to change a default ticks/grid lines arrangement, refer to the Axes help section.

Provide Data per Series

You can specify data for each series individually. This is helpful when you don't have a common data source, but a separate set of values for each series.

To set an individual data source for a series, assign an array of objects to the series' data property. Each object represents a point with the argument and value properties. An argument can be of any type - numeric, string or date-time.

JavaScript
$("#chartContainer").dxChart({
    series: [
        { data: [ {month: 'January', Glendale: 58},{month: 'February', Glendale: 59},{month: 'March', Glendale: 61}] },
        { data: [ {month: 'January', Kirkland: 42},{month: 'February', Kirkland: 44},{month: 'March', Kirkland: 47}] }
    ]
});

There are series types in which there is more than one value per argument, e.g., a candleStick, stock, rangeArea and rangeBar. All the value fields must be listed in the data source's objects. The following code demonstrates how a data source can be defined when a series of the rangeBar type is used.

JavaScript
$("#chartContainer").dxChart({
    series: [
        { data: [{ month: 'January', minValue: 36, maxValue: 43.29},{month: 'February', minValue: 40.68, maxValue: 47.07}] },
        { data: [{month: 'January', minValue: 42.12, maxValue: 49.91},{month: 'February', minValue: 28.33, maxValue: 51.75}] },
        //...
    ]
});

Since properties in the specified data objects can have any name, be sure to indicate which property is a source for arguments and which property(ies) is a source for values. Refer to the following topics for details:

Argument and value axes are generated automatically based on the data provided in the data source. To learn how to specify whether an axis must be continuous or discrete, and how to change default tick/grid lines arrangement, refer to the Axes help section.

Set a Value Field

When setting a common data source for a series in a chart or setting an array of data objects for each series individually, be sure to specify which field(s) must be used as a value's data source and which field must be used as an argument's data source for each series. Refer to the Set an Argument Field topic to learn how to set an argument field.

In most cases, when there is one value per argument, you will use the series' valueField property to set the data source's field whose values will be used as the series' values.

JavaScript
$("#chartContainer").dxChart({
    //...
    series: [
        { valueField: 'Glendale' },
        { valueField: 'Kirkland' }
    ]
});

In certain series types, there are several values per argument. In these instances, the data source's fields must be set using properties specific to each series type. The code below demonstrates these properties for the rangeArea and rangeBar series types.

JavaScript
var dataSource = [
    { month: 'January', min1: 36, max1: 43.29, min2:  42.12, max2: 49.91 },
    //...
];
$("#chartContainer").dxChart({
    //...
    dataSource: dataSource,
    commonSeriesSettings: {
        type: 'rangebar', //type: 'rangearea',
    },
    series: [
        { rangeValue1Field: 'min1', rangeValue2Field: 'max1' },
        { rangeValue1Field: 'min2', rangeValue2Field: 'max2' }
    ]
});

The following code demonstrates how to set value fields for the candleStick and stock series types.

JavaScript
var dataSource = [
    {date: new Date(1994,2,1), lowPrice: 24.00, highPrice: 25.00, openPrice: 25.00, closePrice: 24.875},
    //...
];
$("#chartContainer").dxChart({
    //...
    dataSource: dataSource,
    commonSeriesSettings: {
        type: 'candlestick', //type: 'stock',
    },
    series: {         
         openValueField: 'openPrice',
         closeValueField: 'closePrice',
         lowValueField: 'lowPrice',
         highValueField: 'highPrice'
    }
});

The value axes is generated automatically based on the data provided in the data source. For details on how to customize the value axis, refer to the ValueAxis topic.

Set an Argument Field

When setting a common data source for a series in a chart or setting an array of data objects for each series individually, take care to specify which field(s) must be used as the value's data source and which field must be used as the argument's data source for each series. Refer to the Set a Value Field topic to learn how to set value fields.

Use the series' argumentField property to set argument field name. If there are several series in the chart, set the argument field name within the commonSeriesSettings configuration object. In such an instance, all series will have argument field names specified in one place.

JavaScript
$("#chartContainer").dxChart({
    dataSource: commonDataSource,
    commonSeriesSettings: {
        argumentField: 'month'
    }
    //...
});

The argument axis is generated automatically based on the data provided in the data source. For details on how to customize the value axis, refer to the ArgumentAxis topic.

Update Data Source

The Chart and PieChart widgets can be refreshed in response to data source changes. This allows you to make charts dynamically changeable. Use the Knockout or JQuery approach to refresh your chart. In this topic, you will learn how to do this.

Knockout Data Update

The dataSource option, like any other option from the first level of the chart's configuration object, can be declared as an observable variable. Any change in the option value will be detected and the chart will be refeshed in response to the change.

HTML
<div id="chartContainer" style="height:400px; width: 600px" data-bind="dxChart: { 
    dataSource: observableChartDataSource,
    <!-- ...-->
}"></div>
JavaScript
var myViewModel = {
    observableChartDataSource: ko.observableArray(data),
    //...
};
ko.applyBindings(myViewModel);

The example below demonstrates a chart with an observable data source. Press Start and Stop to begin and pause the data update.

Show Example:
jQuery

JQuery Data Update

The dataSource option, like any other option of the chart's configuration object, can be changed using the jQuery approach.

To access a widget instance, use its jQuery plugin and pass "instance" as a parameter. The following code demonstrates how to do this.

JavaScript
var chart = $("#chartContainer").dxChart("instance");

To set the dataSource configuration option to a new value, pick from the following two approaches:

  • Use the option() function of a widget instance

    Call the option function passing the option name as the first parameter and a new value as the second value.

    JavaScript
    var chart = $("#chartContainer").dxChart("instance");
    var dataSource = chart.option('dataSource', updatedDataSource);
  • Use the widget's plugin

    Call the function that represents the widget's jQuery plugin passing "option" as the first parameter, the name of the required option as the second parameter and a new value for the option as the third parameter.

    JavaScript
    var dataSource = $("#chartContainer").dxChart('option','dataSource', updatedDataSource);

After the option changes, the widget will be refreshed automatically.

The example below demonstrates a chart and pie chart with updated data source. Press John and Mike to update the charts' data.

Show Example:
jQuery