Skip to content

Commit 67280d0

Browse files
vladaskorohodovavladaskorohodova
authored
PivotGrid: update Integration with Chart (DevExpress#6964) (DevExpress#6965)
1 parent e4905a0 commit 67280d0

File tree

7 files changed

+118
-103
lines changed

7 files changed

+118
-103
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ JS-Howto.xml
99
JS-ApiReference-Compact.json
1010
JS-Howto-Compact.json
1111
.DS_Store
12+
.vscode

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/10 Integration with Chart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
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](/api-reference/10%20UI%20Components/dxChart '/Documentation/ApiReference/UI_Components/dxChart/') UI component. To bind these two UI components together, PivotGrid exposes the [bindChart(chart, integrationOptions)](/api-reference/10%20UI%20Components/dxPivotGrid/3%20Methods/bindChart(chart_integrationOptions).md '/Documentation/ApiReference/UI_Components/dxPivotGrid/Methods/#bindChartchart_integrationOptions') method. This article dives deep into the capabilities of this method.
1+
PivotGrid handles large numeric datasets that can be difficult to interpret. For more detailed data visualization, use the [Chart](/api-reference/10%20UI%20Components/dxChart '/Documentation/ApiReference/UI_Components/dxChart/') component. To link PivotGrid with Chart, call the [bindChart(chart, integrationOptions)](/api-reference/10%20UI%20Components/dxPivotGrid/3%20Methods/bindChart(chart_integrationOptions).md '/Documentation/ApiReference/UI_Components/dxPivotGrid/Methods/#bindChartchart_integrationOptions') method. This article explores the features of this method.
22

33
#include btn-open-demo with {
44
href: "https://js.devexpress.com/Demos/WidgetsGallery/Demo/PivotGrid/ChartIntegration/"

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/15 Bind the Chart.md‎

Lines changed: 88 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,129 @@
1-
A pivot grid can be bound only to an existing chart.
1+
PivotGrid can be bound only to an existing Chart.
2+
3+
For example, the following code creates a PivotGrid component and a Chart component:
24

35
---
46
##### jQuery
57

6-
For example, assume you have the following code that creates a pivot grid in the `pivotGridWidget` container and a chart in the `chartWidget` container.
7-
88
<!--HTML-->
9-
<div id="pivotGridWidget" style="height:400px; max-width:700px"></div>
10-
<div id="chartWidget" style="height:400px; max-width:700px"></div>
9+
<div id="pivot-grid"></div>
10+
<div id="chart"></div>
1111

1212
<!--JavaScript-->
1313
$(function () {
14-
$("#pivotGridWidget").dxPivotGrid({ ... });
15-
$("#chartWidget").dxChart({ ... });
14+
$("#pivot-grid").dxPivotGrid({ ... });
15+
$("#chart").dxChart({ ... });
1616
});
1717

18-
---
18+
##### Angular
1919

20-
To bind chart and pivot grid together without changing the default integration properties, call the `bindChart(chart, integrationOptions)`.
20+
<!-- tab: app.component.html -->
21+
<dx-pivot-grid></dx-pivot-grid>
22+
<dx-chart></dx-chart>
2123

22-
---
23-
##### jQuery
24+
##### Vue
2425

25-
<!--JavaScript-->// Passing the chart instance
26-
var chartInstance = $("#chartWidget").dxChart("instance");
27-
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
28-
pivotGridInstance.bindChart(chartInstance);
26+
<!-- tab: App.vue -->
27+
<template>
28+
<DxPivotGrid />
29+
<DxChart />
30+
</template>
31+
<script setup lang="ts">
32+
import DxPivotGrid from 'devextreme-vue/pivot-grid';
33+
import DxChart from 'devextreme-vue/chart';
34+
</script>
2935

30-
<!--------->
36+
##### React
3137

32-
<!--JavaScript-->// Passing the selector of the chart container
33-
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
34-
pivotGridInstance.bindChart('#chartWidget');
38+
<!-- tab: App.tsx -->
39+
import React from 'react';
40+
import PivotGrid from 'devextreme-react/pivot-grid';
3541

36-
<!--------->
42+
const App = () => {
43+
return (
44+
<React.Fragment>
45+
<PivotGrid />
46+
<Chart />
47+
</React.Fragment>
48+
);
49+
}
3750

38-
<!--JavaScript-->// Passing the jQuery element
39-
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
40-
pivotGridInstance.bindChart($('#chartWidget'));
51+
export default App;
4152

4253
---
4354

44-
This method can be called at any point of the application flow. For example, you can bind the chart once it is initialized.
55+
To bind Chart and PivotGrid without changing the default integration properties, call [bindChart(chart, integrationOptions)](/api-reference/10%20UI%20Components/dxPivotGrid/3%20Methods/bindChart(chart_integrationOptions).md '/Documentation/ApiReference/UI_Components/dxPivotGrid/Methods/#bindChartchart_integrationOptions'). This method can be called at any point of the application flow. For example, you can bind the chart once it is initialized:
4556

4657
---
4758
##### jQuery
4859

4960
<!--JavaScript-->
5061
$(function () {
51-
$("#pivotGridWidget").dxPivotGrid({ ... });
52-
$("#chartWidget").dxChart({
62+
$("#pivot-grid").dxPivotGrid({ ... });
63+
$("#chart").dxChart({
5364
// ...
5465
onInitialized: function (e) {
55-
var pivotGridInstance = $("#pivotGridWidget").dxPivotGrid("instance");
56-
pivotGridInstance.bindChart('#chartWidget');
66+
var pivotGridInstance = $("#pivot-grid").dxPivotGrid("instance");
67+
pivotGridInstance.bindChart('#chart');
5768
}
5869
});
5970
});
6071

61-
---
72+
##### Angular
6273

63-
The `bindChart(chart, integrationOptions)` method returns a function that unbinds the chart. If the method has returned **null**, the binding failed.
74+
<!-- tab: app.component.ts -->
75+
// ...
76+
export class AppComponent implements AfterViewInit {
77+
@ViewChild(DxPivotGridComponent, { static: false }) pivotGrid: DxPivotGridComponent;
78+
@ViewChild(DxChartComponent, { static: false }) chart: DxChartComponent;
79+
80+
ngAfterViewInit() {
81+
this.pivotGrid.instance.bindChart(this.chart.instance);
82+
}
83+
}
84+
85+
##### Vue
86+
87+
<!-- tab: App.vue -->
88+
<template>
89+
<DxPivotGrid ref="grid" />
90+
<DxChart ref="chart" />
91+
</template>
92+
<script setup lang="ts">
93+
import { onMounted, ref } from 'vue';
94+
// ...
95+
const grid = ref<DxPivotGrid>();
96+
const chart = ref<DxChart>();
6497

65-
---
66-
##### jQuery
98+
onMounted(() => {
99+
grid.value?.instance?.bindChart(chart.value?.instance);
100+
});
101+
</script>
102+
103+
##### React
67104

68-
<!--JavaScript-->var unbindChart = pivotGridInstance.bindChart('#chartWidget');
105+
<!-- tab: App.tsx -->
106+
import React, { useEffect, useRef } from 'react';
69107
// ...
70-
if (unbindChart)
71-
unbindChart();
108+
109+
const App = () => {
110+
const chartRef = useRef<ChartRef>(null);
111+
const pivotGridRef = useRef<PivotGridRef>(null);
112+
useEffect(() => {
113+
pivotGridRef.current.instance().bindChart(chartRef.current.instance());
114+
}, []);
115+
116+
return (
117+
<React.Fragment>
118+
<PivotGrid ref={pivotGridRef} />
119+
<Chart ref={chartRef} />
120+
</React.Fragment>
121+
);
122+
}
72123

73124
---
74125

126+
If the **bindChart(chart, integrationOptions)** method returns `null`, the binding failed.
127+
75128
#####See Also#####
76129
#include common-link-configurewidget

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/20 Convert Grid Fields into Chart Series.md‎

Lines changed: 17 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,46 @@
1-
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.
1+
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.
22

3-
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:
3+
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:
44

5-
- **true** - row field values go to the arguments; column field values form series.
6-
- **false** - column field values go to the arguments; row field values form series.
5+
- `true` - row field values become arguments; column field values form series.
6+
- `false` (default) - column field values become arguments; row field values form series.
77

8-
---
9-
##### jQuery
10-
11-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
12-
// ...
13-
inverted: false // true
14-
});
15-
16-
---
8+
pivotGridInstance.bindChart(chartInstance, {
9+
// ...
10+
inverted: false // true
11+
});
1712

18-
By default, the **inverted** field is set to **false**.
19-
20-
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.
13+
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.
2114

2215
<div class="simulator-desktop-container" data-view="/Content/Applications/24_1/DataVisualization/Guides/GridChartIntegration/inverted.html, /Content/Applications/24_1/DataVisualization/Guides/GridChartIntegration/inverted.js"></div>
2316

24-
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"*.
25-
26-
---
27-
##### jQuery
17+
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"*.
2818

29-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
19+
pivotGridInstance.bindChart(chartInstance, {
3020
// ...
3121
putDataFieldsInto: "series" // "args"
3222
});
33-
34-
---
3523

36-
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**.
24+
Some data fields may alternate on the Chart plot. To control this behavior, set the **alternateDataFields** field to `true` (default) or `false`.
3725

38-
---
39-
##### jQuery
40-
41-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
26+
pivotGridInstance.bindChart(chartInstance, {
4227
// ...
4328
alternateDataFields: true // false
4429
});
4530

46-
---
47-
48-
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.
31+
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.
4932

5033
<div class="simulator-desktop-container" data-view="/Content/Applications/24_1/DataVisualization/Guides/GridChartIntegration/dataFieldsLayout.html, /Content/Applications/24_1/DataVisualization/Guides/GridChartIntegration/dataFieldsLayout.js"></div>
5134

52-
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.
53-
54-
---
55-
##### jQuery
35+
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.
5636

57-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
37+
pivotGridInstance.bindChart(chartInstance, {
5838
// ...
5939
processCell: function (cellData) {
6040
// Process data here
6141
return cellData; // This line is optional
6242
}
6343
});
64-
65-
---
6644

6745
The **cellData** argument has the following fields:
6846

@@ -100,6 +78,4 @@ The resulting item that will be passed on to the chart data source. The fields o
10078
* **arg**: <span style="font-size:12px">Number | String | Date</span>
10179
The argument of the data item.
10280
* **val**: <span style="font-size:12px">Number | String | Date</span>
103-
The value of the data item.
104-
105-
In this topic, you have discovered how to process data coming from PivotGrid to Chart using the second argument of the [bindChart(chart, integrationOptions)](/api-reference/10%20UI%20Components/dxPivotGrid/3%20Methods/bindChart(chart_integrationOptions).md '/Documentation/ApiReference/UI_Components/dxPivotGrid/Methods/#bindChartchart_integrationOptions') method. The final topic provides an overview of fields that customize the resulting look of Chart.
81+
The value of the data item.

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/30 Customize the Chart/10 Customize the Chart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
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.
1+
In the previous topic, you learned how to process data through the second argument of the **bindChart(chart, integrationOptions)** method. Subtopics in this section cover how to adjust the fields of this argument to modify the Chart appearance.

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/30 Customize the Chart/20 Customize the Series.md‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
11
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.
22

3-
---
4-
##### jQuery
5-
6-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
3+
pivotGridInstance.bindChart(chartInstance, {
74
// ...
85
customizeSeries: function (seriesName, seriesOptions) {
96
// Change series properties here
107
return seriesOptions; // This line is optional
118
}
129
});
13-
14-
---
1510

1611
The function accepts the following arguments.
1712

@@ -20,28 +15,23 @@ Identifies the series.
2015
- **seriesOptions**: <span style="font-size:12px">Object</span>
2116
The properties of the series.
2217
* **axis**: <span style="font-size:12px">String</span>
23-
The name of the axis the series occupies. Has a value only when there are several axes in the chart.
18+
The name of the axis the series occupies. Has a value only when there are several axes in the Chart.
2419
* **pane**: <span style="font-size:12px">String</span>
25-
The name of the pane the series occupies. Has a value only when there are several panes in the chart.
20+
The name of the pane the series occupies. Has a value only when there are several panes in the Chart.
2621

2722
The **seriesOptions** can contain any appearance-related properties from the [series](/api-reference/10%20UI%20Components/dxChart/1%20Configuration/series '/Documentation/ApiReference/UI_Components/dxChart/Configuration/series/') section of the reference.
2823

29-
When series were generated from several data fields, they can be arranged in three different manners.
24+
When series are generated from several data fields, they can be arranged in three different ways:
3025

3126
- *"singleAxis"* - series of all data fields are displayed on a single value axis.
3227
- *"splitAxes"* - series of each data field occupy an individual value axis.
3328
- *"splitPanes"* - series of each data field occupy an individual pane.
3429

35-
To specify the exact manner, use the **dataFieldsDisplayMode** field.
30+
To specify the exact way, use the **dataFieldsDisplayMode** field.
3631

37-
---
38-
##### jQuery
39-
40-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
32+
pivotGridInstance.bindChart(chartInstance, {
4133
// ...
4234
dataFieldsDisplayMode: 'splitAxes' | 'singleAxis' | 'splitPanes'
4335
});
44-
45-
---
4636

4737
[note]If you have set the [putDataFieldsInto](/concepts/05%20UI%20Components/PivotGrid/150%20Integration%20with%20Chart/20%20Convert%20Grid%20Fields%20into%20Chart%20Series.md '/Documentation/Guide/UI_Components/PivotGrid/Integration_with_Chart/#Convert_Grid_Fields_into_Chart_Series') field to *"args"*, **dataFieldsDisplayMode** will be set to *"singleAxis"* forcedly.

‎concepts/05 UI Components/PivotGrid/150 Integration with Chart/30 Customize the Chart/30 Customize the Value Axes and Panes.md‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
1-
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.
1+
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.
22

3-
---
4-
##### jQuery
5-
6-
<!--JavaScript-->pivotGridInstance.bindChart('#chartWidget', {
3+
pivotGridInstance.bindChart(chartInstance, {
74
// ...
85
customizeChart: function (chartOptions) {
9-
// Change chart properties here
6+
// Change Chart properties here
107
return chartOptions; // This line is optional
118
}
129
});
13-
14-
---
1510

1611
The **chartOptions** object contains the following fields.
1712

@@ -20,4 +15,4 @@ Allows you to customize the automatically-created [value axes](/concepts/05%20UI
2015
- **panes**: <span style="font-size:12px">Array</span>
2116
Allows you to customize the automatically-created [panes](/concepts/05%20UI%20Components/Chart/40%20Panes/00%20Overview.md '/Documentation/Guide/UI_Components/Chart/Panes/Overview/'). Each object in this array can contain fields described in the [panes](/api-reference/10%20UI%20Components/dxChart/1%20Configuration/panes '/Documentation/ApiReference/UI_Components/dxChart/Configuration/panes/') property description. When this array holds several objects, use their [name](/api-reference/10%20UI%20Components/dxChart/1%20Configuration/panes/name.md '/Documentation/ApiReference/UI_Components/dxChart/Configuration/panes/#name') field to identify the pane.
2217

23-
The **customizeChart(chartOptions)** function is designed mainly for customizing the automatically-generated chart elements. However, the argument of this function accepts any [property](/api-reference/10%20UI%20Components/dxChart/1%20Configuration '/Documentation/ApiReference/UI_Components/dxChart/Configuration/') 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.
18+
The **customizeChart(chartOptions)** function is designed mainly for customizing the automatically-generated Chart elements. However, the argument of this function accepts any [property](/api-reference/10%20UI%20Components/dxChart/1%20Configuration '/Documentation/ApiReference/UI_Components/dxChart/Configuration/') 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.

0 commit comments

Comments
 (0)