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 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.