Data Binding

This topic tells you how to bind your data to the dxChart, dxPieChart or dxSparkline widget. First, you need to provide data for the chart series. Learn how to do this in the Provide Data section. No matter which widget and series types you are going to use, the approach is always the same.

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.

Provide Data

This section explains how to provide data to a chart directly. To discover how to do this using a data layer, refer to the Using Data Layer section.

To provide data to a chart directly, create an array of objects, each of which specifies series values for a particular argument. These objects can contain data for several series at once. Later on, 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 is more than one value per argument, e.g., the candleStick, stock, bubble, 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 assign your data source to a chart, use the dataSource option as demonstrated in the code below.

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

Now, we can use the provided data source when defining the chart 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, discrete or logarithmic, and how to change a default ticks/grid lines arrangement, refer to the Axes help section.

Set a Value Field

When providing data for a chart series, 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. In this section, you will learn how to specify value fields. 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'
    }
});

Series of the bubble type slightly differ from other series. Along with the value field, it requires the size field to be specified. The code below illustrates how to specify the value and size fields for the bubble series.

JavaScript
var dataSource = [
    { month: 'January', val1: 24, size1: 25, val2: 14, size2: 31  },
    //...
];
$("#chartContainer").dxChart({
    //...
    dataSource: dataSource,
    commonSeriesSettings: {
        type: 'bubble'
    },
    series: [
        { valueField: 'val1', sizeField: 'size1' },
        { valueField: 'val2', sizeField: 'size2' }
    ]
});

The value 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 Value Axis topic.

Set an Argument Field

When providing data for chart series, be sure 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. In this section, you will learn how to specify an argument field. Refer to the Set a Value Field topic to learn how to set value fields.

Use the series' argumentField property to set an 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 Argument Axis topic.

Update Data Source

The dxChart, dxPieChart and dxSparkline 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 chart configuration object option, 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 a pie chart with an updated data source. Press John and Mike to update chart data.

Show Example:
jQuery

Using Data Layer

Data for the dxChart, dxPieChart and dxSparkline widgets can be provided and updated using a data layer. A data layer is a set of complementary components that enables you to read and write data easily. The data layer simplifies working with data no matter what kind of a data source you use. In this section, you will find information on how to use a data layer for providing and updating data.

Provide Data

The Data Layer concept is based on two main objects: DataSource and Store. A DataSource is an object that includes data sorting, grouping, filtering; it also keeps data transformation options and applies them each time data is loaded. A Store is an object that implements a universal interface for reading and modifying data. Stores can be of different types. The following code illustrates how to connect an ODataStore, which contains data from a remote source, to a DataSource object.

JavaScript
var dataStore = new DevExpress.data.ODataStore({
    url: "https://sampleservices.devexpress.com/Northwind.svc/Products",
    key: 'ProductID'
});
var dataSource = new DevExpress.data.DataSource({
    store: dataStore,
    paginate: false
});

NOTE: We recommend turning pagination off. This action will prevent your data source from partitioning.

After you have defined a data source, assign it to a chart using the dataSource option as demonstrated in the code below.

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

For further explanation, refer to the Data Layer topic. To find examples on how to connect your data source with a data layer, see the Data Source Examples topic. Full documentation on the data layer is located in the Reference section.

Update Data Source

For read-write access to data, use a Store directly. To obtain a store instance, create it explicitly, or if you already have a DataSource, call its store() method.

To update a data item specified by a key, use the store.update(key, values) method.

JavaScript
store.update(1, { value: "new value" })
    .done(function(values) {
        // handle successfull updating
    })
    .fail(function(error) {
        // handle error
    });

Note that the second argument of the update(key, values) method contains only the options whose values should be changed in the data item, but not the entire item, because it will be merged with the original item object.

In a common scenario, before updating, you need to load the required item using the store.byKey(key) method.

After the data source has been updated, the chart should be updated as well by calling the load() method of the DataSource object.

The example below demonstrates a chart and a pie chart with an updated data source. In this example, data lies in an ArrayStore that is wrapped into a DataSource. Press John or Mike to update chart data.

For details on data modification in a data layer, refer to the Data Modification topic.

Show Example:
jQuery