Improved total row behavior for Data Grids

The behavior of the total row for the Data Grid component has been enhanced to simplify the setup, and to better support calculations. The change also better aligns the total behavior of the Data Grid component with the behavior of the Fixed Report component.

The new total behavior is designed to automatically include all relevant columns and calculations in the total row, and to automatically apply the appropriate aggregation or calculation.

  • All numeric "data" columns and calculations are now automatically included in the total row by default. It is no longer necessary to flag these columns for inclusion.

  • In previous releases, you had to specify the aggregation type to use in the total row for each column. This is no longer necessary. Table columns shown in the total row automatically use the same aggregation applied to the column values (such as Sum or Count). Note that certain aggregations are not supported in the total row, such as DistinctCount, so any columns using unsupported aggregations are automatically excluded from the total row.

  • In previous releases, it was not possible to apply the calculation used in a calculated column to the total row. Now, calculated columns automatically apply the same calculation to the values in the total row, which means that calculations like percent difference now display the expected results in the total row.

Going forward, the process to display a total row in the grid is much easier:

  • Enable Include Total Row in the component properties.

  • Use the Total Row Header field in the component properties to define a label for the total row, such as "Total" or "Total Expenses".

  • Place the keyword Header in the [Total] column of the DataGridColumns data source, in the row corresponding to the column where you want the total row label to display. Typically this is the column that holds the "sum by" values, or its description column.

  • In the majority of cases, there is no need to further populate the [Total] column with True or False, because all relevant columns are automatically included in the total row. However, in the rare case that you do not want to display a particular column, you can enter False for that column.

The following example shows a DataGridColumns data source with a new [Total] column:

This grid will render as follows in the form. Notice that all relevant columns are included in the total row by default, and calculations are applied to the total row.

The [Total] tag is automatically included in all newly created DataGridColumns data sources. For existing data sources, you must manually add it.

Backward-compatibility considerations

In previous releases, the Data Grid component used a [TotalRow] tag to configure the total row. No columns were included by default. In order to flag a column for inclusion, you were required to specify the aggregation to apply to the total row.

Existing Data Grid components that use the legacy [TotalRow] tag are treated as follows:

  • The Header keyword is still honored in the [TotalRow] column to display the total row label.

  • Any column with a non-blank value in the [TotalRow] column is included in the total row, using the new behavior where the current aggregation or calculation is automatically applied.

Generally speaking, this means that any column that you had previously configured to display in the total row will continue to display in the total row. Although it is possible that a table column may now use a different aggregation in the total row than it was previously configured to use, this should be an extremely rare or non-existent occurrence. Note that DistinctCount aggregation is no longer supported for use in the total row, but since this is a fringe use case, the change is unlikely to affect any existing grids. Calculated columns included in the total row will now automatically use their defined calculation instead of a specified aggregation.

Going forward, you should convert any existing grids with a total row to use the new [Total] column. This can be done very easily:

  • Rename the [TotalRow] column in the DataGridColumns data source to be just [Total].
  • Clear out all values in the column except the Header keyword.

In most cases, this will result in the desired total behavior. If you view the grid and determine that you want to exclude a column that has been automatically included, you can enter False into the [Total] column.