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

Radoslav Karaivanov | Date:
Stamen Stoychev | Date:
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 last focusable element in the template will take focus (if the template contains focusable elements), if there is no focusable element inside then the details row will take focus. When the last focusable element inside the template is reached, hitting tab will move focus to the details row. After hitting shift again the focus will move to the previous data row.

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>()

Methods

Name	Description
expandAll()	Expands all master rows.
collapseAll()	Collapse all master rows.
toggleRow(rowID)	Toggles row state (expanded/collapsed) by row ID.
expand(rowID)	Expands a row by row ID. Does nothing on expanded row.
collapse(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, even for those that require scrolling to reach.
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 interactable.
Should expand the last row and the detail view should visible without the need to scroll.
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, even those out of view.
Should collapse all rows using the collapseAll() method, even those out of view.

Keyboard Navigation:

Should navigate down through a detail view by focusing the whole row and continuing onto the next.
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.
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.

Feature Integration:

Paging:

Should take into account expanded detail views as additional records.
Should move newly expanded detail view to a new page if the current will exceed the max page count.

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.