igxTreeGrid Specification

Owned by

CodeX

Diyan Dimitrov

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Radoslav Mirchev | Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Diyan Dimitrov, Stefan Ivanov	29 Oct 2020	Updating spec format

1. Overview

The igxTreeGrid control is intended to visualize hierarchical data with consistent data schema in the tabular fashion of the igxGrid. Tree Grid's default styling follows Google's material design guidelines and is consistent with the igxGrid.

Objectives

Provide Ignite UI for Angular igx-treegrid component that supports the existing igx-gird features:

Sorting
Filtering
Editing
Paging
Virtualization - Row and column
Multi-column headers
Templates
Row and Cell Selection
Column Summaries
Column hiding
Column pinning
Column moving
Data-binding
Export to Excel

Acceptance criteria

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

...

2. User Stories

Developer

Story 1: As a developer, I want to be able to hide particular columns under certain conditions and show them again when these conditions change and it makes sense to have them visible again.

Story 2: As a developer, I want to be able to freeze some columns by default so the user is unable to move and reorder them around the grid.

Story 3: As a developer, I want to be able to specify if updating the content of the treegrid is allowed or not – is it editable or read-only.

Story 4: As a developer, I want to be able to show a particular node in the hierarchy upon initial rendering of the grid. I need to be able to set the number of levels which are initially expanded below the root level in order for that node’s parent to be expanded and thus the node be visible on initialization.

Story 5: As a developer, I want to be able to decide whether the expand state is persisted or not so when the grid is redrawn for any reason it either keeps this expanded state or resets it (sets it to the initial state).

Story 6: As a developer, I want to specify which columns are allowed to be placed to the left of the grid and serve as the one to represent visually the tree hierarchy. For some columns it makes a lot of sense to do so while for others it does not make any (e.g. imagine a company organization: names, positions and departments make sense to act as tree columns while salary, starting date and type of contract do not).

Story 7: As a developer, I want to be able to offer aggregated information for a given level in the hierarchy of the grid. This can be achieved through a special row that can be either on top of the group of entries as a header or just below it as a footer.

Story 8: As a developer, I want to be able to configure whether the selection is single or multiple. By default, row selection is disabled.

Story 9: As a developer, I want to be able to enable a multiple selection mode in a cascading fashion. By default the multiple selection mode allows the end-user to select records one by one like in a flat grid.

End user

Story 1: As an end user, I need a visual indication in the form of an icon, showing that a given node (root or non-leaf) has children. The icon can be enhanced to further show the specific number of non-leaf or leaf level children that the node has.

Story 2: As an end user, I expect that non-leaf and leaf level nodes are indented in a way that indicates how they relate to their parent.

Story 3: As an end user, I want to be able to filter the entries for a certain column so that only records matching the criterion that I have set are displayed and their parents in a grayed out fashion to provide additional context. Filtering is applied to all hierarchy levels meaning that all nodes matching the criterion are shown by expanding their parents when needed.

Story 4: As an end user, I want to be given the option to sort the records in the tree grid in ascending/descending order by any column, representing property of the entry. Sorting would work between siblings in the data hierarchy and will affect all levels and records recursively.

Story 5: As an end user, when I refresh the grid (or trigger another action that re-renders it) the old state of the layout (expanded/collapsed levels) should be retained and reflected after the grid is redrawn on the screen.

Story 6: As an end user, I want to be able to adjust the size of the columns so that they fit the content in a way that is suitable and useful for me.

Story 7: As an end user, I want to be able to pin a certain column to the left of the tree grid and this way it will always stay visible upon horizontally scrolling the grid.

Story 8: As an end user, I want to hide particular columns when my current needs dictate this. Of course, later on I need to be able to make these columns visible again.

Story 9: As an end user, I want to have the ability to reorder the columns in a way would help me deal with my current task without this causing any change to the hierarchy.

Story 10: As an end user, I expect that tree grids with a lot of records are split into pages with a certain number of items per page and indentation is properly carried over from the current page to the next one.

> ??? Story 11: As an end user, I expect that records can be moved in the hierarchy, which would affect the internal structure of the data shown in the tree grid.

Story 12: As an end user, I want to navigate the hierarchy with the keyboard using:

Up Arrow – go the row above
Down Arrow – go the row below
Right Arrow – expand the node if it has children
Left Arrow – collapse the node
and more... TODO

Story 13: As an end user, I want to have a visualization of the hierarchical belonging of my currently selected item in a toolbar and be able to easily perceive how it is related to the root level of the hierarchy (e.g. an indication similar to the path to a file on the file system).

Story 14: As an end user, I want to have a special row that serves to aggregate information for a set of entries in the grid. This special row can be either on top of the group of entries as a header or just below it as a footer. Such header/footer is usually employed to summarize the data for a certain level of the hierarchy.

3. Functionality

The tree grid shows hierarchical data giving context about records that have children by showing an expand indicator at the beginning of the row and indenting it according to the level it has in the hierarchy. The expand/collapse indicator also serves as a means for navigating the data.

3.1. End-User Experience

Filtering in the tree grid returns all matching records, where for records deeper in the hierarchy it also shows a trace of the direct parent hierarchy up to root level applying a grayed-out style on the parents that are not matching the filtering conditions.

Row and Cell Selection (select all included). Akin to the igx-grid, the tree grid supports none, single, and multiple as modes for row selection, but they work differently given the hierarchical nature of the data in the Tree Grid:

none - row selection is disabled
single - when selecting/deselecting a parent row only it is selected/deselected, its children remain unaffected and so does the parent (checkbox remains unchecked). This is the default mode.
multiple - when selecting/deselecting a parent row all of its child rows are selected/deselected in a cascading fashion. When a parent has some selected and some deselected children, its checkbox is in an indeterminate state. With multiple selection enabled it is also possible to additionally specify its behavior via the cascadeSelection boolean property which is false by default allowing you to select records one by one as in a flat grid (before selection on the left and after it on the right).

When set to true the selection is cascading, resulting in the selection of all children in the tree below the record that the user selects with user interaction (before selection on the left and after it on the right).

Column Summaries are defined on the grid level akin to the flat grid and for any given hierarchical context or level akin to the flat grid with Group-By applied.

3.2. Developer Experience

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Aside from the key combinations "inherited" from the igx-Grid, the Tree Grid should also support the following keyboard interactions, accountable for the expansion and collapsing of parent records:

Keys	Description
Alt + Arrow right / Alt + Arrow down	Expand record
Alt + Arrow left / Alt + Arrow up	Collapse record
Arrow right / Tab	Move right from leftmost cell

3.5. API

Options

Name	Description	Type	Default value	Valid values

Methods

Name	Description	Return type	Parameters

Events

Name	Description	Cancelable	Parameters

4. Test Scenarios

Automation

Basic

Should have the tree-cell as a first cell on every row
Should have correct indentation for every record of each level
Should expand/collapse rows through the UI by adding/removing their respective children in the grid's view underneath
Should expand/collapse rows through the API by adding/removing their respective children in the grid's view underneath
When expand/collapsing rows through the UI the expand/collapse indicators should change
When expand/collapsing rows through the API the expand/collapse indicators should change
Should be able to have a tree-column with a number dataType
Should be able to have a tree-column with a string dataType
Should be able to have a tree-column with a date dataType
Should be able to have a tree-column with a boolean dataType

Expand/Collapse

Should update the current page when collapseAll is invoked
Should update the current page when expandAll is invoked
Should update the paginator when a row of any level is expanded
Should update the paginator when a row of any level is collapsed
Should update the paginator when navigating through pages

Data Transformation

Should transfrom input data into the desired hierarchical structure given primaryKey and foreignKey are specified
Should transform input data into the desired hierarchical structure given childDataKey is specified
Should sort data in the desired hierarchical structure so that sorting is applied for each seperate level of hierarchy
Should correctly flatten the desired hierarchical structure with children being listed under respective parents in the correct order
Should page the flattened data based on paging parameters

Integration

Should persist the indentation after sorting
Should persist the indentation after filtering
Should persist the indentation on all pages when using paging
Should persist the indentation after resizing the tree-column
Should correctly render a template set through a template outlet for a column that is assigned to be the expand one
Should transform a non-tree column into a tree column when pinning it
Should transform a non-tree column into a tree column when hiding the original tree-column
Should transform the first visible column into tree column when pin and hide another column before that
Should transform a hidden column to a tree column when it becomes visible and it is the first column
Should transform a non-tree column into a tree column when moving the original tree-column through API
Should transform a non-tree column into a tree column when moving the original tree-column through UI
Should be able to autosize the tree-column through API
Should be able to autosize the tree-column through UI
Should change cell content alignment of tree-column with number dataType when it is no longer tree-column
Should transform a non-tree column into a tree column when hiding the original tree-column when it is part of a group
Should transform a hidden column to a tree column when it becomes visible and it is the first column and both the original and new tree column are part of the same group
Should transform a hidden column to a tree column when it becomes visible and it is the first column and both the original and new tree column are not part of the same group
Should transform a non-tree column into a tree column when moving it first and both are part of the same group
Should transform a non-tree column of a column group to a tree column when its group is moved first
Should correctly filter a string column using the contains filtering conditions
Should correctly filter a string column using the endswith filtering conditions
Should correctly filter a number column using the greaterThan filtering conditions
Should correctly filter a number column using the lessThan filtering conditions
Should correctly filter a date column using the before filtering conditions
Should correctly filter a date column using the after filtering conditions
Should be able to search for a word in the tree column
Should be able to search for a word in an ordinary column

Selection

Should be able to have checkbox on each row
Should be able to select/deselect all rows (including the rows from all child levels)
Should be able to select row of any level
Should be able to deselect row of any level
Should persist the selection after expand/collapse
Should update header checkbox when reselecting all filtered-in rows
Should return the correct type of cell when clicking on a cell
Should return the correct type of cell when clicking on a child cell

CRUD

Should support adding root row through treeGrid API
Should support adding child rows through treeGrid API
Should support adding child row to null collection through treeGrid API
Should support adding child row to undefined collection through treeGrid API
Should support adding child row to non-existing collection through treeGrid API
Should do nothing when adding child row to a non-existing parent row (invalid parentID).
Should support updating a root row through the treeGrid API
Should support updating a child row through the treeGrid API
Should support updating a child row through the rowObject API
Should support updating a child tree-cell through the treeGrid API
Should support updating a child tree-cell through the cellObject API
Should be able to enter edit mode of a tree-grid column on dblclick, enter and F2
Should be able to enter edit mode of a non-tree-grid column on dblclick, enter and F2
Should be able to edit a tree-grid cell through UI
Should be able to edit a non-tree-grid cell through UI
Should be able to delete a root level row by ID
Should be able to delete a child level row by ID
Should be able to delete a root level row through the row object
Should be able to delete a child level row through the row object
Should emit an event when deleting row by ID
Should emit an event when deleting row through the row object

Keyboard navigation

Up Arrow Key to navigate one cell up. Test in a child and parent rows.
Down Arrow Key to navigate one cell down Test in a child and parent rows.
Left Arrow Key to navigate one cell left (no wrapping between lines) on the current row only.
Right Arrow Key to navigate one cell right on the current row only.
Page Up scroll one page (view port) up.
Page Down scroll one page (view port) down.
Tab move the selection to next cell or next row if the last cell is reached.
Shift + Tab move the selection to previous cell or previous row (last row cell) if the first cell is reached.
Tab if a cell is opened in edit mode next cell or next row first cell (if the last cell is reached) should be opened in edit mode. If the next cell is not editable, it have to be selected.
Shift + Tab If a cell is opened in edit mode the previous cell or previous row (last row cell) if the first cell is reached should be opened in edit mode. If the cell is not editable, it have to be selected.
Alt + Up/Left Arrow Key the cell should stay selected and focused and if the selected cell row has children the row should be collapsed.
Alt + Down/Right Arrow Key the cell should stay selected and focused and if the selected cell row has children the row should be expanded.
Ctrl + Up Arrow Key move to top cell in column.
Ctrl + Down Arrow Key move to bottom cell in column.
Ctrl + Left Arrow Key move to leftmost cell in row.
Ctrl + Right Arrow Key move to rightmost cell in row.
Ctrl + Home move to top left cell in the grid.
Ctrl + End move to bottom right cell in the grid.
Tab/Arrow keys should navigate correctly when we have pinned columns
Space if Row selectors are enabled pressing space on a selected cell should select its row
Esc if a cell is opened in edit mode the cell edit mode should be closed and the cell should stay selected.
Enter/F2 if a cell is editable it should toggle cell edit mode.

Search

Search highlights should work for tree cells
Search highlights should work for root and child rows
Search highlights should work for both flat and hierarchical data
Should navigate search highlights with collapsed rows
Should navigate search highlights with paging
Should navigate search highlights with paging and collapsed rows
Search highlights should work for case sensitive and exact match searches
Should update search highlights when filtering
Should update search highlights when clearing filter
Should update search highlights when sorting
Should update search highlights after pin/unpin column
Should update search highlights after hide/show column

Manual Testing

igxTreeGrid is rendered correctly when initialized in igxTabs
igxTreeGrid is rendered correctly when initialized in igxDialog

5. Accessibility

WAI-ARIA Support In 2014 the W3C finalized their WAI-ARIA specification which defined how to design Web content and Web applications to be more accessible to users with disabilities. The TreeGrid has been designed so that it follows these guidelines.

The list below provides details about what changes have been made to the TreeGrid to support WAI-ARIA. Please note that no special settings are needed to leverage these changes, as they are all enabled by default.