DevExtreme jQuery/JS - 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.

JavaScript
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.

JavaScript
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
JavaScript
var fruitProduction = [
    { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
    { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
];

$(function() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        series: {
            argumentField: 'fruit',
            valueField: 'year2014',
            name: '2014'
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxi-series
        argumentField="fruit"
        valueField="year2014"
        name="2014">
    </dxi-series>
</dx-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})

The PieChart may contain several series that have the same argument field. In this case, you can assign the field's name to the argumentField option of the commonSeriesSettings object.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
    { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
];

$(function() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit'
        },
        series: [
            { valueField: 'year2014', name: '2014' },
            { valueField: 'year2015', name: '2015' },
            { valueField: 'year2016', name: '2016' }
        ]
    });
});
Angular
HTML
TypeScript
<dx-pie-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-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})
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
JavaScript
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() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced'
        },
        seriesTemplate: {
            nameField: 'year'
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced">
    </dxo-common-series-settings>
    <dxo-series-template
        nameField="year">
    </dxo-series-template>
</dx-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})

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 the function.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples", year: 2014, produced: 84 },
    // ...
];

$(function() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced'
        },
        seriesTemplate: {
            nameField: 'year',
            customizeSeries: function(seriesName) {
                // Colors the series "2016" in blue
                return seriesName == 2016 ? { color: 'blue' } : { }
            }
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced">
    </dxo-common-series-settings>
    <dxo-series-template
        nameField="year"
        [customizeSeries]="customizeSeries">
    </dxo-series-template>
</dx-pie-chart>
import { DxPieChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples", year: 2014, produced: 84 },
        // ...
    ];
    customizeSeries(seriesName: string) {
        // Colors the series "2016" in blue
        return seriesName == 2016 ? { color: 'blue' } : { }
    }
}
@NgModule({
    imports: [
        // ...
        DxPieChartModule
    ],
    // ...
})
See Also