JavaScript/jQuery PivotGrid - 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 UI component. To bind these two UI components together, PivotGrid exposes the bindChart(chart, integrationOptions) method. This article dives deep into the capabilities of this method.

View Demo

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

<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({ ... });
});

To bind chart and pivot grid together without changing the default integration properties, call the bindChart(chart, integrationOptions).

// Passing the chart instance
var chartInstance = $("#chartWidget").dxChart("instance");
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
pivotGridInstance.bindChart(chartInstance);

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

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

$(function () {
    $("#pivotGridWidget").dxPivotGrid({ ... });
    $("#chartWidget").dxChart({
        // ...
        onInitialized: function (e) {
            var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
            pivotGridInstance.bindChart('#chartWidget');
        }
    });
});

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

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

See Also

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.

  jQuery

  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 property is set to "series".

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 property is true.

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

Below, use the set of controls under the UI components 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.

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.

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.

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

The seriesOptions can contain any appearance-related properties 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.

pivotGridInstance.bindChart('#chartWidget', {
    // ...
    dataFieldsDisplayMode: 'splitAxes' | 'singleAxis' | 'splitPanes'
});

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('#chartWidget', {
    // ...
    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 needed properties as usual - when you design the chart. They will be merged with the properties returned by the customizeChart(chartOptions) function.