JavaScript/jQuery PivotGrid - Integration with Chart
PivotGrid handles large numeric datasets that can be difficult to interpret. For more detailed data visualization, use the Chart component. To link PivotGrid with Chart, call the bindChart(chart, integrationOptions) method. This article explores the features of this method.
Bind the Chart
PivotGrid can be bound only to an existing Chart.
For example, the following code creates a PivotGrid component and a Chart component:
- <div id="pivot-grid"></div>
- <div id="chart"></div>
- $(function () {
- $("#pivot-grid").dxPivotGrid({ ... });
- $("#chart").dxChart({ ... });
- });
To bind Chart and PivotGrid without changing the default integration properties, call bindChart(chart, integrationOptions). This method can be called at any point of the application flow. For example, you can bind the chart once it is initialized:
- $(function () {
- $("#pivot-grid").dxPivotGrid({ ... });
- $("#chart").dxChart({
- // ...
- onInitialized: function (e) {
- var pivotGridInstance = $("#pivot-grid").dxPivotGrid("instance");
- pivotGridInstance.bindChart('#chart');
- }
- });
- });
If the bindChart(chart, integrationOptions) method returns null
, the binding failed.
See Also
Convert Grid Fields into Chart Series
The second argument of the bindChart(chart, integrationOptions) method customizes the contents, behavior, and appearance of the Chart component. This section describes the fields in this argument that handle data procession.
When binding Chart to PivotGrid, specify how to form Chart series from PivotGrid fields. PivotGrid data fields always become Chart value fields. Row and column fields can form either arguments or series. The inverted field specifies the following values:
true
- row field values become arguments; column field values form series.false
(default) - column field values become arguments; row field values form series.pivotGridInstance.bindChart(chartInstance, { // ... inverted: false // true });
In the example below, toggle the check box to update the inverted field. When this field is false
, values of the "2014" column field become the arguments, while values of the "Europe" row field form series. When inverted is true
, the result is reversed.
When PivotGrid contains multiple data fields, they can become sets of series or sets of arguments. To specify this behavior, use the putDataFieldsInto field and choose "series" (default) or "args".
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- putDataFieldsInto: "series" // "args"
- });
Some data fields may alternate on the Chart plot. To control this behavior, set the alternateDataFields field to true
(default) or false
.
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- alternateDataFields: true // false
- });
Below, use the controls under the UI components to change the putDataFieldsInto and alternateDataFields fields. Observe how the "Total" and "Avg" data fields depend on these values.
To process data in a specific way, assign a callback function to the processCell field. This function will be called for each data cell of PivotGrid.
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- processCell: function (cellData) {
- // Process data here
- return cellData; // This line is optional
- }
- });
The cellData argument has the following fields:
- rowPath: Array
The path to the data cell by row field values. - rowPathFormatted: Array
Same as rowPath, but with format and customizeText applied. - rowFields: Array
Objects representing row fields. - maxRowLevel: Number
A zero-based index that indicates the maximum currently-expanded row level. Equals to 0 when grid has no row fields at all, 1 when all rows are collapsed, 2 when at least one first-level row is expanded, etc. - columnPath: Array
The path to the data cell by column field values. - columnPathFormatted: Array
Same as columnPath, but with format and customizeText applied. - columnFields: Array
Objects representing column fields. - maxColumnLevel: Number
A zero-based index that indicates the maximum currently-expanded column level. Equals to 0 when the grid has no column fields at all, 1 when all columns are collapsed, 2 when at least one first-level column is expanded, etc. - dataFields: Array
Objects representing data fields. - dataValues: Array
Data of the current cell. Contains several values if the pivot grid has several data fields. - dataIndex: Number
A zero-based index that indicates which data field and value from the dataFields and dataValues arrays respectively are currently in process. If you have only one data field, dataIndex always equals to 0. - visible: Boolean
Indicates whether the current cell will be passed to the chart or not. Equals to true if the cell belongs to the deepest expanded level. This field is changeable. For example, if you need to prevent a cell from being added to a chart series, set visible to false. - chartDataItem: Object
The resulting item that will be passed on to the chart data source. The fields of this object are customizable.- series: String
The name of the series to which the data item will belong. - arg: Number | String | Date
The argument of the data item. - val: Number | String | Date
The value of the data item.
- series: String
Customize the Series
If you need to customize the automatically-formed series, assign a callback function to the customizeSeries field. This function will be called once for each series.
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- customizeSeries: function (seriesName, seriesOptions) {
- // Change series properties here
- return seriesOptions; // This line is optional
- }
- });
The function accepts the following arguments.
- seriesName: String
Identifies the series. - seriesOptions: Object
The properties of the series.- axis: String
The name of the axis the series occupies. Has a value only when there are several axes in the Chart. - pane: String
The name of the pane the series occupies. Has a value only when there are several panes in the Chart.
- axis: String
The seriesOptions can contain any appearance-related properties from the series section of the reference.
When series are generated from several data fields, they can be arranged in three different ways:
- "singleAxis" - series of all data fields are displayed on a single value axis.
- "splitAxes" - series of each data field occupy an individual value axis.
- "splitPanes" - series of each data field occupy an individual pane.
To specify the exact way, use the dataFieldsDisplayMode field.
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- dataFieldsDisplayMode: 'splitAxes' | 'singleAxis' | 'splitPanes'
- });
Customize the Value Axes and Panes
To customize the automatically-generated value axes or panes, assign a callback function to the customizeChart field. This function will be called once - before rendering the Chart.
- pivotGridInstance.bindChart(chartInstance, {
- // ...
- customizeChart: function (chartOptions) {
- // Change Chart properties here
- return chartOptions; // This line is optional
- }
- });
The chartOptions object contains the following fields.
- valueAxis: Array
Allows you to customize the automatically-created value axes. Each object in this array can contain fields described in the valueAxis property description. When this array holds several objects, use their name field to identify the axis. - panes: Array
Allows you to customize the automatically-created panes. Each object in this array can contain fields described in the panes property description. When this array holds several objects, use their name field to identify the pane.
The customizeChart(chartOptions) function is designed mainly for customizing the automatically-generated Chart elements. However, the argument of this function accepts any property of Chart that configures the UI component's appearance. Alternatively, you can specify the properties when you design the Chart. They merge with the properties returned by the customizeChart(chartOptions) function.