Integration with Chart

PivotGrid visualizes large amounts of data that are numeric - this can be hard to understand. To make your data more clear to a viewer, visualize it in the Chart widget. To bind these two widgets together, PivotGrid exposes the bindChart(chart, integrationOptions) method. This article dives deep into the capabilities of this method.

View Demo

Bind the Chart

A pivot grid can be bound only to an existing chart.

See Also

For example, assume you have the following code that creates a pivot grid in the pivotGridWidget container and a chart in the chartWidget container.

jQuery
HTML
JavaScript
<div id="pivotGridWidget" style="height:400px; max-width:700px"></div>
<div id="chartWidget" style="height:400px; max-width:700px"></div>
$(function () {
    $("#pivotGridWidget").dxPivotGrid({ ... });
    $("#chartWidget").dxChart({ ... });
});
AngularJS
HTML
JavaScript
<div ng-controller="widgetController">
    <div id="pivotGridWidget" style="height:400px; max-width:700px" dx-pivot-grid="pivotGridOptions"></div>
    <div id="chartWidget" style="height:400px; max-width:700px" dx-chart="chartOptions"></div>
</div>
angular
    .module('myApp', ['dx']);
    .controller("widgetController", function ($scope) {
        $scope.pivotGridOptions = { ... };
        $scope.chartOptions = { ... };
    });

angular.element(document).ready(function () {
    angular.bootstrap(document, ['myApp']);
});
Knockout
HTML
JavaScript
<div id="pivotGridWidget" style="height:400px; max-width:700px" data-bind="dxPivotGrid: pivotGridOptions"></div>
<div id="chartWidget" style="height:400px; max-width:700px" data-bind="dxChart: chartOptions"></div>
var viewModel = {
    pivotGridOptions: { ... },
    chartOptions: { ... }
};

ko.applyBindings(viewModel);

To bind these two widgets together without changing the default integration options, call the bindChart(chart, integrationOptions) using one of the following constructions.

JavaScript
// Passing the chart instance
var chartInstance = $("#chartWidget").dxChart("instance");
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
pivotGridInstance.bindChart(chartInstance);
JavaScript
// Passing the selector of the chart container
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
pivotGridInstance.bindChart('#chartWidget');
JavaScript
// Passing the jQuery element
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
pivotGridInstance.bindChart($('#chartWidget'));

This method can be called at any point of the application flow. For example, you can bind the chart once it is initialized.

jQuery
JavaScript
$(function () {
    $("#pivotGridWidget").dxPivotGrid({ ... });
    $("#chartWidget").dxChart({
        // ...
        onInitialized: function (e) {
            var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
            pivotGridInstance.bindChart('#chartWidget');
        }
    });
});
AngularJS
JavaScript
angular
    .module('myApp', ['dx']);
    .controller("widgetController", function ($scope) {
        $scope.pivotGridOptions = { ... };
        $scope.chartOptions = {
            // ...
            onInitialized: function (e) {
                var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
                pivotGridInstance.bindChart('#chartWidget');
            }
        };
    });

angular.element(document).ready(function () {
    angular.bootstrap(document, ['myApp']);
});
Knockout
JavaScript
var viewModel = {
    pivotGridOptions: { ... },
    chartOptions: { 
        // ...
        onInitialized: function (e) {
            var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
            pivotGridInstance.bindChart('#chartWidget');
        }
    }
};

ko.applyBindings(viewModel);

The bindChart(chart, integrationOptions) method returns a function that unbinds the chart. If the method has returned null, the binding failed.

JavaScript
var unbindChart = pivotGridInstance.bindChart('#chartWidget');
// ...
if (unbindChart)
    unbindChart();

The next topic shows how PivotGrid transforms its data before sending it to Chart and how you can govern this process.

Convert Grid Fields into Chart Series

The second argument of the bindChart(chart, integrationOptions) method allows you to customize the contents, behavior and appearance of the resulting chart. This subtopic describes those fields of this argument that consider data procession.

When binding a chart to a pivot grid, you can specify how to form chart series from grid fields. Data fields from the grid always become value fields in the chart. However, row and column fields can form either arguments or series. Use the inverted field to specify this. The following values are accepted by this field.

  • true - row field values go to the arguments; column field values form series.
  • false - column field values go to the arguments; row field values form series.

    JavaScript
    pivotGridInstance.bindChart('#chartWidget', {
        // ...
        inverted: false // true
    });

By default, the inverted field is set to false.

In the example below, toggle the check box to change the value of the inverted field. When this field is false, values of the "2014" column field go to the arguments, while values of the "Europe" row field form series. When inverted is true - the result is inverted.

When the grid contains several data fields, they may be turned into either sets of series or sets of arguments. To specify this, set the putDataFieldsInto field to "series" or "args" correspondingly. By default, this option is set to "series".

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    putDataFieldsInto: "series" // "args"
});

Moreover, several data fields may either alternate on the chart plot or not. To specify this feature, set the alternateDataFields field to true or false respectively. By default, this option is true.

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    alternateDataFields: true // false
});

Below, use the set of controls under the widgets to change the putDataFieldsInto and alternateDataFields fields. You can observe how the "Total" and "Avg" data fields depend on the values of these fields.

If you need to process data in some specific way, assign a callback function to the processCell field. This function will be called for each data cell of the pivot grid.

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    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.

In this topic, you have discovered how to process data coming from PivotGrid to Chart using the second argument of the bindChart(chart, integrationOptions) method. The final topic provides an overview of fields that customize the resulting look of Chart.

Customize the Chart

In the previous topic, you learned how to process data using the second argument of the bindChart(chart, integrationOptions) method. Subtopics in this section show how to use fields of this argument to change the appearance of the chart.

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.

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    customizeSeries: function (seriesName, seriesOptions) {
        // Change series options here
        return seriesOptions; // This line is optional
    }
});

The function accepts the following arguments.

  • seriesName: String
    Identifies the series.
  • seriesOptions: Object
    The options 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.

The seriesOptions can contain any appearance-related options from the series section of the reference.

When series were generated from several data fields, they can be arranged in three different manners.

  • "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 manner, use the dataFieldsDisplayMode field.

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    dataFieldsDisplayMode: 'splitAxes' | 'singleAxis' | 'splitPanes'
});
NOTE
If you have set the putDataFieldsInto field to "args", dataFieldsDisplayMode will be set to "singleAxis" forcedly.

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.

JavaScript
pivotGridInstance.bindChart('#chartWidget', {
    // ...
    customizeChart: function (chartOptions) {
        // Change chart options 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 option 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 option 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 option of Chart that configures the widget's appearance. Alternatively, you can specify the needed options as usual - when you design the chart. They will be merged with the options returned by the customizeChart(chartOptions) function.

Show Example:
AngularJS
Knockout
jQuery

In this example, Chart is integrated with PivotGrid using the bindChart(chart, integrationOptions) method. PivotGrid has two data fields: "Total" and "Average". Series generated from each field occupy an individual pane. Additionally, the panes are colored differently using the customizeChart function.


                                    

                                    

In this example, Chart is integrated with PivotGrid using the bindChart(chart, integrationOptions) method. PivotGrid has two data fields: "Total" and "Average". Series generated from each field occupy an individual pane. Additionally, the panes are colored differently using the customizeChart function.


                                    

                                    

In this example, Chart is integrated with PivotGrid using the bindChart(chart, integrationOptions) method. PivotGrid has two data fields: "Total" and "Average". Series generated from each field occupy an individual pane. Additionally, the panes are colored differently using the customizeChart function.