Summaries Specification

1. Revision history

Version	User	Date	Notes
0.1	Zdravko Kolev	29.08.18	Grid summaries
0.2	Stefan Ivanov	21.11.18	Grid summaries, Tree-grid summaries, Hierarchical summaries
0.3	Nadia Robakova	29.11.18	Grid summaries add automation test plan
0.4	Zdravko Kolev	29.11.18	Updating functionality and additional features sections
0.5	Stefan Ivanov	09.05.19	Updating functionality and additional features sections
0.6	Zdravko Kolev	06.07.20	Add `showSummaryOnCollapse` images
0.7	Hristo Anastasov	02.10.20	Update expectations on summary result localization
0.8	Maria Tsvyatkova	17.03.21	Update summary result localization
0.9	Maria Tsvyatkova	21.10.21	Update summary result formatting and localization

Simeon Simeonov | Date:
Zdravko Kolev | Date: 08/10/2019
Konstantin Dinev | Date:
Slav Karaslavov | Date:

Objectives

Summaries allow you to display types of summaries within a data container.

2. User Stories

As a developer, I want to:

implement summaries per column, so that I can give the user quick access to data summaries.
have already set defaults summaries, depending on the type of data in the column, so that I can save time:
- numeric: min, max, average, sum, count
- string: count
- date: latest, earliest, count
- time: latest, earliest, count (count - counts all cells that are Not empty)
be able to modify/edit/delete the "default summaries", so that they fit my specific needs.
provide UI to enable the user to see the summaries per column per type of summary. The UI is visible only if summaries are switched on.
provide UI to enable the user to switch on and off summaries per column per summary function.
specify which summaries are hidden per column using a simple property (disabledSummaries), so I can selectively control the display of summaries without extensive customization.
have global grid summaries UI positioned bottom fixed above the pager and above the horizontal scroll.
have per-data-island summaries positioned within the tree grid / grouped flat grid body at the end of the data island. tree grid grouped flat grid

...

As a user, I want to:

to toggle on and off specific summaries of a single column, or the entire grid.
summaries to be relevant to the type of data per column (numeric, string, data).
the summary of the column to be a function of all column values, even if paging is applied.
a summary result of a column shows a label and a value. And is positioned at the appropriate location below corresponding column data in a summary UI.
summaries to be displayed in a table layout.
that if a column is moving the summaries move accordingly.
that editing a cell will automatically update the total summaries.
that hiding/deleting/modifying a column will hide/delete/modify its total summaries accordingly.
ability to toggle the visibility of specific summaries (e.g., 'min', 'max', 'count') for a single column directly without additional coding.
that sorting will not change the summaries values.
that when multiple summaries stack at the end of data island, there is a clear visual indication where one group of summaries ends and another one begins.
that a summary row is distinguishable from the following group by row
ZK implement custom summary compound of two or more columns (values)
summaries to be displayed localized, in the grid locale by default. ...

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

Additional Features Added

set the position of the summary row for the data-island-related summaries to bottom (default) and top
implement custom functions.
support an advanced summary results container that adjusts its size and layout to the number of summaries switched on.

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

summaries are switched on per column
all data records are accessible from each column
each summary type has a label (min/max etc)
all similar types of summaries are positioned in one row, e.g. min first row, max second row.
all summary labels are aligned at the start of the column. When a grid is grouped by or a tree gird has summaries, the data-island summary rows have the first-column summary aligned with an indent that reflects the nesting.
When filtering is applied, the summaries are recalculated and show a function of the filtered data only.
Summary row indentation based on Summary level – Possible improvements? Stefan to provide possible solutions
Summaries with paging, open summary on next page – Follow GroupBy example, summaries should be rendered only in the next page.
Change summary operands runtime – For example: I want to change min and max with sum. We should support this. Summary Operand could be passed to a column. Grid to recalculate with reflow().
Grid with Transaction – On Row Updating, Deleting or Adding – Summaries should be updated, before commit (Slav – if performance is affected, we will change that)
Row Editing – While editing, summaries are not updated; Summaries should be updated on Done button click.
One event before ‘operate’ and one after ‘operate’.
The height of summary rows are defined below ordered from top to bottom by display densities: comfortable, cosy, compact (summaries width match the width of the column they belong to)
Templated columns don’t have a summary result if enabled on the column.
When the rows are grouped the summary provides access only to the grouped data, not to the whole data
The disabledSummaries property in allows developers to exclude specific summary types (e.g., 'min', 'max', 'count') from displaying within the grid’s summary row for a column.
Default column type pipes and locale should also apply to summary results, unless specifically specified by a custom summary by defining a defaultFormatting: false for the custom summary result.

The summaries inherit the grid display density

3.1. End-User Experience

3.2. Developer Experience

3.3. Globalization/Localization

Localization applied to the grid and to columns would also apply to the corresponding summaries out of the box.

3.4 User Interface

The background colors for per-level summary and global/root summary are different in order to allow the user to distinguish between the two, moreover, the former scrolls along with the grid cells, while the latter is fixed at the bottom of the grid.

per-level summary background color grays 100
global/root summary background color grays 300

flat grid

Grouped flat grid

Expanded grouped flat grid with showSummaryOnCollapse

Collapsed grouped flat grid with showSummaryOnCollapse

tree grid

3.5 Feature integration

GroupBy - There is showSummaryOnCollapse property that manages summaries visibility on Group row collapse/expands action. If showSummaryOnCollapse is set to true, the summary row will be visible on Grouped row collapse action. Default showSummaryOnCollapse value is false.
Excel Export - There is an exportSummaries option in IgxExcelExporterOptions that specifies whether the exported data should include the grid's summaries. Default exportSummaries value is false.

The IgxExcelExporterService will export the default summaries for all column types as their equivalent excel functions so they will continue working properly when the sheet is modified.

The exported file includes a hidden column that holds the level of each DataRecord in the sheet. This level is used in the summaries to filter out the cells that need to be included in the summary function.

In the table below, you can find the corresponding Excel formula for each of the default summaries.

Data Type	Function	Excel Function
`string`, `boolean`, `number`, `currency`, `percent`	count	="Count: "&COUNTIF(start:end, recordLevel)
	min	="Min: "&MIN(IF(start:end=recordLevel, rangeStart:rangeEnd))
	max	="Max: "&MAX(IF(start:end=recordLevel, rangeStart:rangeEnd))
	average	="Avg: "&AVERAGEIF(start:end, recordLevel, rangeStart:rangeEnd)
	sum	="Sum: "&SUMIF(start:end, recordLevel, rangeStart:rangeEnd)
`date`	count	="Count: "&COUNTIF(start:end, recordLevel)
	earliest	="Earliest: "& TEXT(MIN(IF(start:end=recordLevel, rangeStart:rangeEnd)), format)
	latest	="Latest: "&TEXT(MAX(IF(start:end=recordLevel, rangeStart:rangeEnd)), format)

3.6. Keyboard Navigation

The summary cell is focusable. If we are at the last column cell and press arrow down, we should focus the summary.
From Real cell - Ctrl + end, Ctrl + home – focus only real cell, as it is implemented in the GroupBy feature.
[TBD] From summary cell – Ctrl + end, Ctrl + home

3.7. API

Options

Name	Description	Type	Default value	Valid values
`disabledSummaries`	Excludes specified summary operands from display for a column. Accepts an array of strings representing summary keys to hide (e.g., `['min', 'max', 'count']`).	`string[]`	`[]`	`['min', 'max', 'count']`, etc.

Methods

Name	Description	Return type	Parameters
`operate`	Returns a IgxSumamryResult[] object, which contains the default summaries for the column	`IgxSumamryResult[]`	`columnData`, `allData`, `fieldName`

Events

Name	Description	Cancelable	Parameters

4. ARIA Support

Specify only if applicable

5. Assumptions and Limitations

Assumptions	Limitation Notes

6. References

Specify all referenced external sources, incl. competitors’ links. Remove before publishing outside Infragistics

7. Test Scenarios

Automation

Basic

Summaries can be set for a column
Enable/disable runtime summaries
Change summary operand at runtime
Test summaries for different types: through grid API
- Number – Min, Max, Count, Sum, Avg
- Date – Count, Earliest, Latest
- Boolean – Count
- String – Count
Verify that setting disabledSummaries hides specified summaries for a column upon initialization.
Ensure that modifying disabledSummaries at runtime updates displayed summaries without a page reload.
Adding of custom Summary
Confirm that custom summary types in disabledSummaries are hidden as expected.
Summaries when there are empty values in the cells
Disable/Enable summary for only one column which has(Summary row should be hidden/shown)
Should be able to change 'hasSummary' property runtime and to recalculate grid sizes correctly
Verify summaries are correct when scrolling vertically and horizontally
Verify summaries are correct when summaryFormatter is applied
Verify summaries with extended summary operands apply column formatting depending on the defaultFormatting property of the IgxSummaryResult.

Integration Scenarios

Sorting: will not change the summaries
Filtering
- When filter data the summaries will be updated corresponding to the filtered data
- When filter with no items found the Summaries should be correct
Column Moving: When moving a column the summaries should be moved with the column
Column Resizing: When resizing a column its summary should be resized, too
Pinning
- When pin/unpin a column is summary should be moved, too
- Summaries in the pinned column should stay when scrolling horizontally
Paging: The summaries for all the data should be reviewed in each page
MCH: Summaries should be enabled only for a column, not for the column group columns
Crud without transactions
- Cell Editing: When update a cell summary should be updated
- Row Editing: Update a row and Click Done – Summary should be updated
- Row Editing: Update a row and Click Cancel – Summary should not be updated
- Update a cell from API. Summaries should be updated
- Update a row with API. Summaries should be updated
- Row Adding: When adding a row all t6he summaries should be updated
- Row Adding: Add a row in an empty grid. Summaries should be correct
- Row Deleting: When deleting a row the summaries should be updated
- Row Deleting: Delete all the rows in the grid. Summaries should be correct
Crud with transactions
- Update a cell: Update a cell Summaries should be updated. Commit the transaction summaries should be correct
- Update a cell: Undo transactions after a cell is updated the summaries should be refreshed. Redo transaction. Summaries should be updated
- Update a row: Update a row and commit the transaction, Summaries should be updated
- Update a row and Undo Transaction. Summaries should be updated. Redo transaction. Summaries should be updated
- Add Row: Summaries should be updated. Undo/Redo summaries should be updated
- Delete Row: Summaries should be updated. Commit the transaction. Summaries should be updated
- Delete Row: Delete all rows and commit the transaction. The summaries should stay.
Hiding
- Hide a column which has summary: Its summary should be hidden also
- Show column which has summary: it summary should be shown
- Hide/show the only one column which has summary: Summary row should be hide/show
- Recalculate summary row after hide/show column

Summaries with grouping

Summary for all the groups should be previewed
Summary calculation mode: Parent Only/ Child Only/ both
Enable/disable runtime summaries
Test position of the summary row bottom and top
Test alignment for summary row on each group
When collapse a group its summary should hide
When expand a group the summary should be shown
Enable/disable runtime summaries: Should be hidden/shown for all the group rows
Test with 2 or 3 grouped columns
Remove group column only the default summary should be previewed
KB navigation: Arroe Up/Down/ Tab/Shif+Tab/Ctr+End/Cntr+Home
Hiding: Hide/Show grouped column: summary should be hidden/shown
Paging: Summaries should be correct on paging
Filtering: only filtered rows should have summary
Collapse all: Summaries for grouped rows should be hidden
Crud operation

Summaries in treeGrid

Summary calculation mode: Parent Only/ Child Only/ both
Tree grid flat data+ summaries
Enable/disable runtime summary for a column
Test position of the summary row bottom and top
Vertical and horizontal scrolling
KB navigation: Arroe Up/Down/ Tab/Shif+Tab/Ctr+End
Test summaries for different types: through grid API
- Number – Min, Max, Count, Sum, Avg
- Date – Count, Earliest, Latest
- Boolean – Count
- String – Count
Verify summaries for the root
Verify summaries for children
Paging: should show correct summaries
Crud operations
Filtering should have summaries for filtered data only
Hiding: Hide column with summary (test when hide the only one column with summary)