DevExtreme React - Bind Series to Data
This article describes two ways of binding series to data. To decide which way to use, check whether or not names for series are provided by a data source field. If so, you need to use a series template. Otherwise, you can bind series to data directly. For example, assume that you have the following data source.
var fruitProduction = [ { fruit: "Apples", year: 2014, produced: 84 }, { fruit: "Apples", year: 2015, produced: 82 }, { fruit: "Apples", year: 2016, produced: 90 }, { fruit: "Oranges", year: 2014, produced: 72 }, { fruit: "Oranges", year: 2015, produced: 70 }, { fruit: "Oranges", year: 2016, produced: 76 } ];
Depending on the configuration, this data source can produce either two series, named "Apples" and "Oranges", or three series: "2014", "2015" and "2016", but in both these cases, these names are provided by a data source field: fruit
or year
respectively. This is the case when you need to use a series template. Consider another data source.
var fruitProduction = [ { fruit: "Apples", year2014: 84, year2015: 82, year2016: 90 }, { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 } ];
In this case, you can have up to three series bound to the year2014
, year2015
and year2016
fields respectively, but note that there is no data field that provides names for them. Instead, you need to specify the names using the name option. This is the case when you can bind series to data directly.
Directly
To bind a series to data directly, specify which data source field provides arguments and which provides values. For this purpose, use the argumentField and valueField options of the series configuration object.
jQuery
var fruitProduction = [ { fruit: "Apples", year2014: 84, year2015: 82, year2016: 90 }, { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 } ]; $(function() { $("#chartContainer").dxChart({ dataSource: fruitProduction, series: { argumentField: 'fruit', valueField: 'year2014', name: '2014' } }); });
Angular
<dx-chart [dataSource]="fruitProduction"> <dxi-series argumentField="fruit" valueField="year2014" name="2014"> </dxi-series> </dx-chart>
import { DxChartModule } from 'devextreme-angular'; // ... export class AppComponent { fruitProduction = [ { fruit: "Apples", year2014: 84, year2015: 82, year2016: 90 }, { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 } ]; } @NgModule({ imports: [ // ... DxChartModule ], // ... })
Commonly, a chart contains several series, and many of them have the same argument field. In this case, you can assign the name of this field to the argumentField option of the commonSeriesSettings object.
jQuery
var fruitProduction = [ { fruit: "Apples", year2014: 84, year2015: 82, year2016: 90 }, { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 } ]; $(function() { $("#chartContainer").dxChart({ dataSource: fruitProduction, commonSeriesSettings: { argumentField: 'fruit' }, series: [ { valueField: 'year2014', name: '2014' }, { valueField: 'year2015', name: '2015' }, { valueField: 'year2016', name: '2016' } ] }); });
Angular
<dx-chart [dataSource]="fruitProduction"> <dxo-common-series-settings argumentField="fruit"> </dxo-common-series-settings> <dxi-series valueField="year2014" name="2014"></dxi-series> <dxi-series valueField="year2015" name="2015"></dxi-series> <dxi-series valueField="year2016" name="2016"></dxi-series> </dx-chart>
import { DxChartModule } from 'devextreme-angular'; // ... export class AppComponent { fruitProduction = [ { fruit: "Apples", year2014: 84, year2015: 82, year2016: 90 }, { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 } ]; } @NgModule({ imports: [ // ... DxChartModule ], // ... })
The following series types need more than one value field or additional data fields.
Bubble Series
Need one argumentField, one valueField, and one sizeField.Financial Series
Need one argumentField and four value fields: openValueField, closeValueField, highValueField and lowValueField.Range Series
Need one argumentField and two value fields: rangeValue1Field and rangeValue2Field.
Bubble Series Demo Financial Series Demo Range Series Demo
See Also
Using a Series Template
To bind series to data using a series template, start with setting common options for all resulting series in the commonSeriesSettings object. Particularly, make sure that you have set the argumentField and valueField.
After that, use the seriesTemplate.nameField option to specify which data source field provides names for series.
jQuery
var fruitProduction = [ { fruit: "Apples", year: 2014, produced: 84 }, { fruit: "Apples", year: 2015, produced: 82 }, { fruit: "Apples", year: 2016, produced: 90 }, { fruit: "Oranges", year: 2014, produced: 72 }, { fruit: "Oranges", year: 2015, produced: 70 }, { fruit: "Oranges", year: 2016, produced: 76 } ]; $(function() { $("#chartContainer").dxChart({ dataSource: fruitProduction, commonSeriesSettings: { argumentField: 'fruit', valueField: 'produced', // or other data fields type: 'bar' }, seriesTemplate: { nameField: 'year' } }); });
Angular
<dx-chart [dataSource]="fruitProduction"> <dxo-common-series-settings argumentField="fruit" valueField="produced" type="bar"> </dxo-common-series-settings> <dxo-series-template nameField="year"></dxo-series-template> </dx-chart>
import { DxChartModule } from 'devextreme-angular'; // ... export class AppComponent { fruitProduction = [ { fruit: "Apples", year: 2014, produced: 84 }, { fruit: "Apples", year: 2015, produced: 82 }, { fruit: "Apples", year: 2016, produced: 90 }, { fruit: "Oranges", year: 2014, produced: 72 }, { fruit: "Oranges", year: 2015, produced: 70 }, { fruit: "Oranges", year: 2016, produced: 76 } ]; } @NgModule({ imports: [ // ... DxChartModule ], // ... })
If you need to change options of a particular series, return an object with them from the seriesTemplate.customizeSeries function. This object will be merged with the commonSeriesSettings object. To identify a series, use the argument passed to this function.
jQuery
var fruitProduction = [ { fruit: "Apples", year: 2014, produced: 84 }, // ... ]; $(function() { $("#chartContainer").dxChart({ dataSource: fruitProduction, commonSeriesSettings: { argumentField: 'fruit', valueField: 'produced', type: 'bar' }, seriesTemplate: { nameField: 'year', customizeSeries: function(seriesName) { // Changes the type of the series "2016" from the common "bar" to "line" return seriesName == 2016 ? { type: 'line' } : { } } } }); });
Angular
<dx-chart [dataSource]="fruitProduction"> <dxo-common-series-settings argumentField="fruit" valueField="produced" type="bar"> </dxo-common-series-settings> <dxo-series-template nameField="year" [customizeSeries]="customizeSeries"></dxo-series-template> </dx-chart>
import { DxChartModule } from 'devextreme-angular'; // ... export class AppComponent { fruitProduction = [ { fruit: "Apples", year: 2014, produced: 84 }, // ... ]; customizeSeries(seriesName: string) { // Changes the type of the series "2016" from the common "bar" to "line" return seriesName == 2016 ? { type: "line" } : { } } } @NgModule({ imports: [ // ... DxChartModule ], // ... })
See Also
If you have technical questions, please create a support ticket in the DevExpress Support Center.