jQuery DataGrid - summary
A summary is a grid feature that provides a synopsis of data contained in the grid. A summary consists of several items. A summary item displays a value that is a product of applying an aggregate function to the data of a specific column.
There are two types of summary in DataGrid: group and total. The group summary is calculated on a group of data, which is segregated during grouping. To specify the items of the group summary, declare an array of objects and assign it to the summary.groupItems field.
The total summary is calculated on all data contained in the grid. To specify the items of the total summary, declare an array of objects and assign it to the summary.totalItems field.
calculateCustomSummary
Name | Type | Description |
---|---|---|
component |
The widget's instance. |
|
name |
The summary item's name. |
|
summaryProcess |
Indicates the stage of the summary item calculation; equals 'start', 'calculate' or 'finalize'. |
|
value | any |
If the custom summary item is calculated by a column, this field contains the value from a cell of this column. Otherwise, it contains a whole object from the data source. |
totalValue | any |
The resulting summary item's value. |
If predefined aggregate functions do not meet your requirements, implement a custom one and assign it to the calculateCustomSummary option. This function will be called for each summary item whose summaryType property is set to 'custom'.
When implementing the function, you can access useful information through the object passed to this function as its argument. Use the name field of this object to identify the summary item.
To access data, use the value field. This data depends on whether you have set the column field of the summary item or not. If you have, the value field contains the value from a cell of this column. Otherwise, it contains a whole object from the data source.
The calculation of a summary item value is conducted in several phases. Usually, you need to initialize totalValue on start. Then, you modify totalValue in the calculation phase. In the final phase, you adjust totalValue. To identify the current phase, check the value of the summaryProcess field.
The following code demonstrates a general structure of the calculateCustomSummary function. In this code, the totalItems array contains two custom summary items. Within the calculateCustomSummary function, the name field identifies each summary item. Actions that follow depend on the calculation stage, which is obtained using the summaryProcess field.
jQuery
$(function () { $("#dataGridContainer").dxDataGrid({ // ... summary: { totalItems: [ { summaryType: 'custom', name: 'CustomSummary1' }, { summaryType: 'custom', name: 'CustomSummary2' } ], calculateCustomSummary: function (options) { // Calculating "CustomSummary1" if (options.name == 'CustomSummary1') { if (options.summaryProcess == 'start') { // Initializing "totalValue" here } if (options.summaryProcess == 'calculate') { // Modifying "totalValue" here } if (options.summaryProcess == 'finalize') { // Assigning the final value to "totalValue" here } } // Calculating "CustomSummary2" if (options.name == 'CustomSummary2') { // ... // Same "if" statements here } } } }); });
Angular
<dx-data-grid ... > <dxo-summary [calculateCustomSummary]="calculateSummary"> <dxi-total-item summaryType="custom" name="customSummary1"> </dxi-total-item> <dxi-total-item summaryType="custom" name="customSummary2"> </dxi-total-item> </dxo-summary> </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular'; // ... export class AppComponent { calculateSummary (options) { // Calculating "CustomSummary1" if (options.name == 'CustomSummary1') { if (options.summaryProcess == 'start') { // Initializing "totalValue" here } if (options.summaryProcess == 'calculate') { // Modifying "totalValue" here } if (options.summaryProcess == 'finalize') { // Assigning the final value to "totalValue" here } } // Calculating "CustomSummary2" if (options.name == 'CustomSummary2') { // ... // Same "if" statements here } }; } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
See Also
groupItems[]
The group summary provides a synopsis of a group of data. Groups of data are formed in the process of grouping. The group summary contains several items. Each item displays a value that is a product of applying an aggregate function to a group of data.
To specify the items of the group summary, declare an array of objects, each of which contains at least two fields: column and summaryType. The column field specifies the identifier of the column that provides data for an aggregate function. The summaryType specifies the aggregate function to be applied. The following code snippet shows how to declare two summary items.
jQuery
$(function () { $("#dataGridContainer").dxDataGrid({ // ... summary: { groupItems: [{ column: 'Age', summaryType: 'avg' }, { column: 'LastName', summaryType: 'count' }] } }); });
Angular
<dx-data-grid ... > <dxo-summary> <dxi-group-item column="Age" summaryType="avg"> </dxi-group-item> <dxi-group-item column="LastName" summaryType="count"> </dxi-group-item> </dxo-summary> </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular'; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
A group summary item may be located either in the group row or the group footer. By default, the group row holds all summary items. To locate a summary item in the group footer, set the showInGroupFooter option of this item to true.
See Also
skipEmptyValues
Specifies whether or not to skip empty strings, null and undefined values when calculating a summary.
Specified in the summary object, this option affects all summaries in the grid. In addition, the same option can be specified for an individual summary. It will override the global setting.
jQuery
$(function () { $("#dataGridContainer").dxDataGrid({ // ... summary: { totalItems: [{ // ... name: 'customSummary1', summaryType: 'custom' }], calculateCustomSummary: function (options) { if (options.name == 'customSummary1') { if (options.summaryProcess == 'start') { options.totalValue = 0; } if (options.summaryProcess == 'calculate') { if (e.value) { options.totalValue++; } } } } } }); });
Angular
<dx-data-grid ... > <dxo-summary [calculateCustomSummary]="calculateSummary"> <dxi-total-item summaryType="custom" name="customSummary1"> </dxi-total-item> </dxo-summary> </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular'; // ... export class AppComponent { calculateSummary (options) { if (options.name == 'customSummary1') { if (options.summaryProcess == 'start') { options.totalValue = 0; } if (options.summaryProcess == 'calculate') { if (e.value) { options.totalValue++; } } } }; } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
texts
Depending on their type, summary items use one of predefined text patterns specified in the summary.texts object. For example, summary items of the 'avg' type use the pattern specified by the avg field of the texts object.
By default, a summary item is located in the column that provides data for it. This column is called the "parent column". However, a summary item may be located in any other column or in a group row. To specify text patterns for such summary items, use options with the OtherColumn addition in their name. For example, summary items of the 'avg' type located outside their parent column use the pattern specified by the avgOtherColumn field of the texts object.
When implementing a pattern, you can access the summary item value with applied format using position marker 0. If the summary item is placed outside its parent column, you can also access the caption of the parent column using position marker 1. Place each of these position markers within curly brackets.
totalItems[]
The total summary, which is located in the grid footer, provides a synopsis of all data contained in the grid. It contains several summary items. Each item displays a value that is a product of applying an aggregate function to the data of a specific column.
To specify the items of the total summary, declare an array of objects, each of which contains at least two fields: column and summaryType. The column field specifies the identifier of the column that provides data for an aggregate function. The summaryType specifies the aggregate function to be applied. The following code snippet shows how to declare two summary items.
jQuery
$(function () { $("#dataGridContainer").dxDataGrid({ // ... summary: { totalItems: [{ column: 'Age', summaryType: 'avg' }, { column: 'LastName', summaryType: 'count' }] } }); });
Angular
<dx-data-grid ... > <dxo-summary> <dxi-total-item column="Age" summaryType="avg"> </dxi-total-item> <dxi-total-item column="LastName" summaryType="count"> </dxi-total-item> </dxo-summary> </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular'; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
By default, a summary item is placed in the column that provides data for it. If you need to place it in another column, assign the identifier of this column to the showInColumn option.
See Also
If you have technical questions, please create a support ticket in the DevExpress Support Center.