Grid Master Detail

Grid Master Detail Specification

1. Revision History

Version	User	Date	Notes
0.1	Stefan Ivanov	November 01, 2019	Initial draft
0.2	Maya Kirova	November 01, 2019	Initial draft for Developer Experience and ApIs
0.3	Stamen Stoychev	November 29, 2019	Navigation changes

Radoslav Karaivanov | Date:
Stamen Stoychev | Date: 11/29/2019
Konstantin Dinev | Date: 11/01/2019

2. Overview

Provide functionality in the igxGrid that would allow each of its records to act as a master, which upon expansion will show a details template with content contextual to the current record.

3. User Stories

As a developer...

1. I expect that Master Detail functionality works along all other grid features

2. I expect that an icon indicator is rendered for each row allowing it to be expanded/collapsed

3. I expect that I can provide an arbitrary layout within the details template

4. I expect that I can expand/collapse certain rows programmatically

5. I expect that the expansion state is persisted

As an end user

1. I want to be able to expand a row to show its details layout

2. I want to be able to collapse a row to hide its details layout

3. I want to be able to select and focus elements from the details layout

4. I want to be able to navigate between the elements from the details layout with the keyboard

5. I want to be able to see the items I have expanded before, the next time I look at the grid

Acceptance criteria

The details are template that can render any layout desired
Details are displayed after the master (grid row) is "expanded"
Child view states are preserved during scrolling

4. Functionality

4.1. End User Experience

4.2. Developer Experience

Initialization

A details template is defined by creating a template inside a container marked with the structural directive igxGridDetail.

    <igx-grid ... >
         <ng-template igxGridDetail let-dataItem>
              <!-- Custom detail template content here -->
        </ng-template>
    </igx-grid>

Context of the template is the master record data, so that value from the master record can be displayed in the detail template. For example:

    <igx-grid ... >
         <ng-template igxGridDetail let-dataItem>
            <div *ngIf="dataItem.Category">
                <header>{{dataItem.Category.CategoryName}}</header>
                <span>{{dataItem.Category.Description}}</span>
            </div>
        </ng-template>
    </igx-grid>

This feature is specific to the igxGrid and is not inherited in the other grid components - TreeGrid, HierarchicalGrid.

Grid Pipes

There is an additional pipe responsible for adding the child detail views for each expanded master row. The expansion state is applied from the expansionStates property. States are stored in key-value pairs [row identifier, expansion state]. The property gets/sets the current expansion states and supports two-way binding:

       <igx-grid [(expansionStates)]='expansionState' >
         <ng-template igxGridDetail let-dataItem>
              <!-- Custom detail template content here -->
        </ng-template>
    </igx-grid>

Expand/Collapse indicators

All master rows render an expander indicator. Their expand/collapse indicators are rendered as part of the first visible cell, similarly to the TreeGrid. Their related icon can be customized via the igxRowExpandedIndicator/igxRowCollapsedIndicator directives:

    <igx-grid ... >
         <ng-template igxRowExpandedIndicator>
            <igx-icon role="button" fontSet="material">remove</igx-icon>
        </ng-template>
        <ng-template igxRowCollapsedIndicator>
            <igx-icon role="button" fontSet="material">add</igx-icon>
        </ng-template>
         <ng-template igxGridDetail let-dataItem>
             <!-- Custom detail template content here -->
        </ng-template>
    </igx-grid>

No header expand/collapse indicator is available out of the box.

Feature Integration

Sorting
Filtering
Paging
Multi-column headers
Multi-row layouts
Hiding
Pinning
Moving
Summaries
Updating
Selection - works only on data cells.
Row selectors
GroupBy
Search - works only on data cells.

Arrow keys

When navigating through or inside master rows navigation works like in normal grid.

When navigating with up/down arrow keys through a details row, the whole details row is scrolled in view and is focused.
Tab/Shift+Tab

When navigating inside master rows navigation works like in normal grid.

When navigating with Tab and the next element is a details row, the whole row will take focus and then will allow tabbing trough the template content (if the template contains focusable elements). When the last focusable element is reached, hitting tab will move focus to the next available cell in the next row.

When navigating with Shift + Tab inside master rows navigation works like in normal grid.

When navigating with Shift + Tab and the next element is a details row, the whole row will take focus and then one of two things will occur. Another Shift + Tab will focus the last available cell in the previous row. Alternatively, hitting Tab will tab through the template content (if the template contains focusable elements).

4.6. API

Inputs

Name	Description	Type	Default value	Valid values
expansionStates	Gets/Sets the current expansion state of the master records. Contains key-value pairs [row ID, expansion state, which is true if expanded, false if collapsed] that define the expanded state of the data rows.	Map<any, boolean>	new Map<any, boolean>()

Outputs

Name	Description	Type
onRowToggle	Emitted when the expanded state of a row is changed.	IRowToggleEventArgs

Methods

Name	Description
expandAll()	Expands all master rows.
collapseAll()	Collapse all master rows.
toggleRow(rowID)	Toggles row state (expanded/collapsed) by row ID.
expandRow(rowID)	Expands a row by row ID. Does nothing on expanded row.
collapseRow(rowID)	Collapses a row by row ID. Does nothing on collapsed row.

5. ARIA Support

Specify only if applicable

6. Assumptions and Limitations

Assumptions	Limitation Notes
Tab navigation inside the custom detail template is left up to the browser and may not update the master grid scroll position in case the next focused element is outside the visible view port.
When templating a grid inside the details view that has a `<igx-column>` definitions, the parent grid will also render those templated columns.	Since the igxGrid selects all columns inside the template (including the descendants due to the multi-column header implementation) its column collection will be updated based on the nested child columns as well.

7. Test scenarios

Automation

Basic:

Should render an expand icon for all rows.
Should correctly expand a basic detail view, update expansionStates and the context proved should be correct.
Should render a detail view with dynamic elements and they should be clickable/focusable.
Should persist state of rendered templates, such as expansion state of expansion panel, checkbox state, etc. after scrolling them in and out of view.
Should persist state of rendered templates, such as expansion state of expansion panel, checkbox state, etc. after expanding and collapsing the parent row.
Should expand the last row and the scrollbar should be updated.
Should update view when setting a new expansionState object.
Should update rendered detail templates after grid data is changed.
Should expand and collapse a row in view by using the expand(rowID) and collapse(rowID) methods.
Should expand a row out of view by using the expand() method and update expansionStates.
Should collapse a row out of view by using the collapse() method and update expansionStates.
Should toggle a row expand state by using the toggleRow(rowID) method.
Should expand all rows using the expandAll() method and the expansion state should be updated.
Should collapse all rows using the collapseAll() method and the expansion state should be updated.

Keyboard Navigation:

Should navigate down through a detail view by focusing the whole row and continuing onto the next with arrow down.
Should navigate down through a detail view partially out of view by scrolling it so it becomes fully visible.
Should navigate down through a detail view completely out of view by scrolling to it.
Should navigate up through a detail view by focusing the whole row and continuing onto the next with arrow up.
Should navigate up through a detail view partially out of view by scrolling it so it becomes fully visible.
Should navigate up through a detail view completely out of view by scrolling to it.
Should focus detail row first, then continue to the focusable elements in it and continue onto the next row when using Tab.
Should focus the last focusable element in detail first and go in reverse order of all elements when tabbing through detail view using Shift+Tab.
Should expand and collapse using Alt + Right/Down and Alt + Left/Up without losing focus on current row.
Should expand and collapse using Alt + Right/Down and Alt + Left/Up at the bottom of the grid without losing focus.
Should navigate to the correct row/cell when using the navigateTo method in a grid with expanded detail views.
Should navigate to the last cell in the grid using Ctrl + End.
Should navigate to the first cell in the grid using Ctrl + Home.
Should navigate to the last row using Ctrl + ArrowDown when all rows are expanded.
Should navigate to the first row using Ctrl + ArrowUp when all rows are expanded.
Should navigate to the next row using Ctrl + ArrowDown when focused a template container before.

Feature Integration:

Paging:

Should not take into account expanded detail views as additional records.
Should persist template state after paging to a page with fewer records and paging back.

Hiding:

Should set the expand/collapse icon to the new first visible column when hiding the first column.

Pinning:

Should keep/move the expand/collapse icon to the correct column when pinning the first column or another one.
Should render detail view correctly when expanding a master row and there are pinned columns.

Moving:

Should keep the expand/collapse icon in the first column, even when moving a column in first place.
Should keep the expand/collapse icon in the first column, even when moving a column out of first place.

Selection

Should exclude expanded detail views when doing range cell selection

Row Selection

Should not render row selection checkbox for detail views.
Should highlight only the master row when selecting it and not the detail row.

GroupBy Summaries

Should correctly position summary rows when summary row position is top after grouping by and detail views for the group rows are expanded.
Should correctly position summary rows when summary row position is bottom after grouping by and detail views for the group rows are expanded.
Should correctly position summary rows when summary row position is top after grouping by and detail views for the group rows are collapsed.
Should correctly position summary rows when summary row position is bottom after grouping by and detail views for the group rows are collapsed.

Multi Row Layout

Should render expand/collapse icon in the column with visible index 0.
Should expand detail view without breaking multi-row layout.
Should navigate down through a detail view by focusing the whole row and continuing onto the next with arrow down in multi-row layout grid.
Should navigate up through a detail view by focusing the whole row and continuing onto the next with arrow up in multi-row layout grid.