igxGrid Specification

igxGrid Specification

Contents

1. Revision history

2. Overview

3. User Stories

4. Functionality

   4.1. End User Experience

   4.2. Globalization/Localization

   4.3. User Interface

   4.4. Navigation

   4.4.1. Keyboard navigation

   4.5. API

5. ARIA support

6. Assumptions and Limitations

7. Test Scenarios

   7.1 Virtualization

   • Automation

   • Manual

   7.2 Auto-Sizing

   7.3 Keyboard Navigation

1. Revision history

Version	User	Date	Notes
0.1	Zdravko Kolev	Sep 29, 2018	Add Revision History section
0.2	Zdravko Kolev	Oct 05, 2018	Update Keyboard Navigation spec
0.3	Zdravko Kolev	Oct 05, 2018	Add keyboard navigation test scenarios
0.4	Zdravko Kolev	Oct 10, 2018	Add more kb navigation scenarios
0.5	Zdravko Kolev	Oct 15, 2018	Add end user story for blur on wheel scroll
0.6	Galina Edinakova	May 10, 2019	Hide pager when there are no records to show
0.6.1	Martin Pavlov	Jul 17, 2019	Adding Known Limitations
1.0	Zdravko Kolev	Mar 06, 2020	Updating keyboard navigation section
1.1	Stefan Ivanov	Mar 26, 2020	Updating keyboard navigation section
1.2	Nadia Robakova	Apr 01, 2020	Updating keyboard navigation test plan with header navigation
1.3	Zdravko Kolev	Dec 18, 2020	Update wiki based on new active node changes
1.3	Zdravko Kolev	Feb 02, 2021	'-ed' and '-ing' events change

2. Overview

Grid's default styling follows Google's material design guidelines.

Objectives

Provide Ignite UI for Angular igx-grid component that supports the following features:

• Sorting

• Filtering

• Editing

• Paging

• Virtualization - Row and column

• Grouping

• Multi-column headers

• Templates

• Row and Cell Selection

• Cell Merging

• Collapsible column groups

• Column hiding

• Column pinning

• Column moving

• Column Summaries

• Data-binding

• Export to excel

3. User Stories

Developer

Story 1: As a citizen developer, I want to implement a sortable grid control in my application, so that I give users the option to sort the column values alphabetically and in ascending/descending order. The scope of the sorting should be a single column since due to the fewer columns at hand there is no immediate need for multi-column sorting.

Story 2: As a citizen developer, I want to be able to freeze a column (which will move it left until it becomes the leftmost) and the header rows and these will always stay visible in grid layout when the user scrolls.

Story 3: As a citizen developer, I want to implement an editable grid control in my application, so that end users can update cell values or a read-only grid so that end users could not change its data.

Story 4: As a citizen developer, I want to be able to insert column templates in the grid to deliver custom content to the users.

Story 5: As a citizen developer, I want to implement a grid control in my application that supports multi selection, so that the end users may select multiple rows in the grid.

Story 6: As a citizen developer, I want to implement a grid control in my application, so that I can visualize effectively (with paging or horizontal/vertical scroll) large sets of data.

Story 7: As a citizen develop, I want to be able to have filterable columns in the grid so that users could see only data sets they are interested in (using combo dropdown menus in the row header) or search for a particular cell text in an outside global search and get filter down results based on the search value.

Story 8: As a citizen developer, I want to implement a grid with column hiding so that the users may choose which columns are visible in the grid at a given moment by making the necessary selections in a dropdown menu listing all available columns.

Story 9: As a citizen developer, I want to have column cells merge (i.e. only visual) when neighboring rows cells have identical values so that the grid is easier for reading by users.

Story 10: As a citizen developer, I want to implement a grid supporting fixed and continuous virtualization, so that I can load large data sets in the grid without affecting its performance.

Story 11: As a citizen developer, I want to implement a responsive grid in my application that gives the end user best readability and UX for his/her device screen (devices with screen width below a breakpoint get a list-like grid layout).

Story 12: As a citizen developer, I want to implement total summaries.

End user

Story 1: As an end user, I want the grid to be responsive, so that I can get:

• grid layout on desktop environment
• grid layout with hidden columns on tablet-size touch environment
• list-like grid layout on phone-size touch environment

Story 2: As an end user, I want the grid to be touch-friendly, so that I can scroll, navigate, sort and filter the grid on touch-only environment.

Story 3: As an end user, I want to get a pop up modal window when I edit a cell (enter/change values) with confirm/cancel buttons in it, so that I can edit the grid easier on small-screen devices where cell height or row width may be too narrow to enter data directly in grid.

Story 4: As an end user, I expect that the row height for the grid is uniform and sufficient to allow easy and unambiguous selection.

Story 5: As an end user, I expect ultimate performance and instantaneous record loading capabilities that make scrolling as smooth as in a native application with local data.

Story 6: As an end user, I expect to be able to hide particular columns that I am not interested in and in case, I later need information for something that I have hidden, to be able to show again the column.

Story 7: As an end user, I expect that if multiple selection is enabled, I would get a select button allowing me to select accumulatively multiple items at a time. If I want to discard the current selection, I have to be in the normal mode and click anywhere to select a new item. This behavior is similar to some native apps working with list items and tiles.

Story 8: As an end user, I expect to have a sorting indicator per column that tells me if the records in that column have been sorted or not and in what fashion (ascending or descending).

Story 9: As an end user, I expect that the frozen columns are styled accordingly e.g. by dropping a shadow over the rest of the grid, indicating that upon scrolling horizontally they will stay attached to the left edge of the grid.

Story 10: As an end user, I expect that row headers have a distinctive visual treatment that helps me distinguish them from the rows with data records.

Story 11: As an end user, I expect that charts, such as a sparkline, can be rendered within the grid if necessary and they take in account the available cell area.

Story 12: As an end user, I expect styling capabilities allowing me to set the cell background color and the cell content font color to a custom color provided via its hex encoded string.

Story 13: As an end user, I expect, to see an icon in the column header that indicates column summaries option.

Story 14: As an end user, I expect, to toggle on and off specific summaries of single column.

Story 15: As an end user I expect, the summary of the column on to be a function of all column values, even if paging is applied.

Story 16: As an end user, I expect a summary of a column show a label and a value. Positioned right below the column in a grid footer (above the pager?). The footer should be defined as another part of the grid.

Story 17: As an end user I expect, if I have more than one type of summary per column. They are positioned on different rows or on the same row as long as there is one summary per column depending on my needs.

Story 18: As an end user I expect, If I have one type of summary pre each column to have them positioned in one row.e.g., 5 column having average Summary.

Story 19: As an end user I expect, relevant options for summaries for each column. e.g., Min or max summaries are not relevant for a Product Name column.

Story 20: As an end user, I expect to identify when there is no summary for that column .

Story 21: As an end user, I expect, that if a column is moving the summaries move accordingly.

Story 22: As an end user, I expect the summary of the column to be re-calculated on applied filter or not depending on my needs.

Story 23: As an end user In case of filtered summary, I expect the label to change (filtered summary) and to update the rest of the column summaries.

Story 24: As an end user, I do not expect sorting to change my summaries values or position.

Story 25: As an end user, I expect that adding or deleting a row(s) will automatically update the total summaries.

Story 26: As an end user I expect, that editing a cell will automatically update the total summaries.

Story 27: As an end user I expect, that hiding a column will hide its total summaries as well.

Story 28: As an end user I expect to blur the active cell element on scroll wheel, this applies only for selected cell element, if the focus in on a column header or summary, blur wont be performed

Acceptance criteria

The grid has the following achieved objectives:

• Sorting

• Filtering

• Editing

• Paging

• Virtualization (local) - Row and column

• Remote Virtualization - Row only

• Templates

• Row and Cell Selection

• Column pinning

• Data-binding

4. Functionality

Description for all functionalities.

• Sorting - the grid sorting must be configurable per column, alphabetically and in ascending/descending order. Clicking on the header of a sorted column, reverses the sorting order. Sorting Specification

• Filtering - filter on column level based on repeating cell values must be supported by the grid. For the initial version of the component, when the end-user clicks on the filter icon in the column header, he/she will see a container with dropdown and input element, and to be able to select filtering condition from the dropdown. The input element will be used to contain the filtering condition value. Action buttons will be provided - Reset and Filter. Operations UI Specification.

• Editing - cell contents may be set as editable per column. All cells but the header ones may have built-in editing form. Editing Specification

• Paging - the grid pagination is decoupled and provided by the pager component. If visible, the pager toolbar on arrow taps/clicks will transition the user to the next/previous page. A button to jump to first/last and next/prev page is also available. The pager will be hidden when there are no records to show in the grid.

• Virtualization (local) Virtualization is a feature of the igxGrid that reduces the number of active in-memory and DOM objects, as a result boosting performance when binding to large sets of data. igxGrid uses the IgxForOfDirective in order to virtualize its content both vertically (rows) and horizontally (columns). It works by rendering only the data is currently visible in the grid. Elements outside of the visible view port are loaded on demand as they are scrolled into view by the end-user. This feature is enabled by default, meaning that the grid will always virtualize the content that is not currently in the view.

• Remote Virtualization remote virtualization works the same like the local Virtualization with the difference that the data is requested on demand from the server. To implement remote virtualization the developer needs to handle the onDataPreLoad event and request the necessary data from the server asynchronously.

• Grouping - grid should support functionality that enables the user to employ the data in one or more columns in a grid as a primary and secondary criteria for organizing the records in the group in groups.

• Multi-column headers - "grouping" of selected columns visualized through accordingly rendered nesting of column headers. Multi column headers specifications.

• Templates - the grid cells must support template insertion to allow rich web content in the grid.

• Selection - single row and multi-row selection must be supported by the grid. Selection type is set through an option and returns row id index or row data.

• Cell merging - cell merging is a visual enhancement to the grid cell structure. When enabled, rows with identical values in a column will merge for better readability. If the user rearranges the row sequence, the cells unmerge.

• Collapsible column groups - grid should have Collapsible column groups functionality, part of the multi-column headers feature, which provides a way to collapse/expand a column group to a smaller set of data.

• Column hiding - the grid should have the option for the user to select which columns are visible. In mobile view on small devices, only columns that fully fit in the screen estate and one that partially fits will be automatically selected in the column hiding menu. Should the user want to see additional columns, he/she must navigate to the column hiding menu and select/deselect columns.

• Column Pinning - grid's most-left columns and top rows must be lockable and remain at fixed position during scrolling. The setting which columns/rows are locked (i.e. Column pinning) must be exposed though an API property. Locked columns/rows could NOT be hidden or deleted.

• Column moving - the column moving will be handled by a separate directive that will change column indices.

• Column Summaries - grid should allow displaying of data summaries within its container. Summaries Specification.

• Data Binding - any type of services could be used for data binding. The Grid will focus on presenting data and delegate data access to a service.

• Load on Demand - the shouldGenerate public property allows for re-generation of columns when data arrives asynchronously from the creation of the control. Additionally the isLoading input can be used to show a loading template that can be modified.

• Export to excel - grid should provide the ability data to be exported into a Microsoft Excel document.

4.1 End User Experience

The grid component must be responsive and have two display modes - list-like and grid-like layout.

The grid layout will:

• have vertical and horizontal scroll if more rows/columns are available than could fit in the screen estate.

• have hidden columns that by default are all columns that could not fit in the screen width (left most columns are visible by default). The user can select from a multi select drop down which columns to become visible. The developer could assign columns priority index, override the default logic and define the columns that must remain unhidden on small screen devices.

The list layout will:

• transform the grid layout to a list when the width goes below listDisplayWidth. The following responsive vertical rendering logic is applied:

List-like layout:

The header row (if header exists) becomes the left most column with repeating values. All other rows transpose into a column where the first cell for a gird row is snapped to the last cell of the previous grid row.

• The list layout is only vertically scrollable. Column sorting must be disabled. Filtering is only available for the header columns.

• If the combined cell content length exceeds the screen width, text is wrapped automatically.

4.2. Globalization/Localization

The grid must support localization for different cultures/languages, though additional languages on top of English are out of scope.

4.3. User Interface

Sample grid layout

4.4. Navigation

The grid is scrollable on both axes using the igx-scroll functionalities. It supports keyboard, mouse and touch navigation.

4.4.1 Keyboard Navigation

• Arrow Key Up to navigate one cell up (no wrapping)

• Arrow Key Down to navigate one cell down (no wrapping)

• Arrow Key Left to navigate one cell left (no wrapping between lines)

• Arrow Key Right to navigate one cell right (no wrapping between lines)

• Page Up scroll one page (viewport) up

• Page Down scroll one page (viewport) down

• Ctrl + Arrow Key Up move to top cell in column

• Ctrl + Arrow Key Down move to bottom cell in column

• Ctrl + Left Arrow Key or Home move to leftmost cell in row

• Ctrl + Right Arrow Key or End 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

• Enter and F2 to enter edit mode

• Esc to exit edit mode

• Alt + Right Arrow Key expands: parent Treegrid row, or collapsed row of a master-detail grid, or collapsed row of a hierarchical grid

• Alt + Down Arrow Key expands: parent Treegrid row, or collapsed row of a master-detail grid, or collapsed row of a hierarchical grid

• Alt + Left Arrow Key collapses: parent Treegrid row, or expanded row of a master-detail grid, or expanded row of a hierarchical grid

• Alt + Up Arrow Key collapses: parent Treegrid row, or expanded row of a master-detail grid, or expanded row of a hierarchical grid

• Arrow left goes to header cell on the left

• Arrow right goes to header cell on the right

• Arrow up goes to header cell above if any (multiple header rows exist for Multi-Column Headers and Multi-Row Layouts)

• Arrow down goes to header cell below (multiple header rows exist for Multi-Column Headers and Multi-Row Layouts) or body cell on the first row for the respective column

• Arrow left goes to the actionable element (e.g. icon button) on the left

• Arrow right goes to the actionable element (e.g. icon button) on the right

• Arrow left goes to the summary column on the left

• Arrow right goes to the summary column on the right

• Arrow up goes to the body cell on the last row for the respective column

• Arrow down goes to footer if any

Behavior

Tab moves the activation across the grid elements in the following order:

1. Enters the grid and lands on Toolbar / Group by Area if existing
2. The first cell in the top header row
3. The first cell in the top body row/ grouped row
4. The summary of the column
5. Pager UI
6. Leaves the grid

Shift + Tab move the activation in reverse order in relation to the order described above

In order to navigate within each of the tab stops, the right arrow key should be used (or left key, if RTL is enabled).

• Toolbar container - tab moves focus to the next actionable element inside the toolbar.
• Header container - with right arrow key press the first header will be activated. On header kb navigation we are navigating only through the parent headers and will read the child headers, without going through them with activation.
• Tbody container - navigation will occur with arrow keys, there is no tab key press navigation. Tab will go to the next tab stop element or to the next focusable element (templated column with input, button and etc.) if any. If we have row selectors? Do we skip focusing on them on tab key press when the row selectors are enabled? When the last row cell is reached with constant left arrow key press, the down arrow key should be used in order to move to the next row, and then the active element would be the last row cell from the new row.
• Summary container - The whole container is focused on. With shift + tab you go back to tbody. Arrow keys for active element navigation. Home and end are working as expected.
• Footer container - use the right arrow key for navigation within the summary cells. Again, if there is a custom template with input, button or another tab stop element it will be focused on tab navigation. If we have paging, we do not skip focusing on the pager's focusable elements.

Ctrl + arrow key left/right have the same behavior for tbody cells, summary cells, and header cells.

Header navigation on an activated header cell

• Ctrl + Arrow up sorts the column in ASC order (if already sorted in ASC order it unsorts the column)

• Ctrl + Arrow down sorts the column in DSC order (if already sorted in DSC order it unsorts the column)

• Space toggles the column selection state

• Alt+ L opens the advanced filter dialog

• Ctrl + Shift + L opens the excel style filter or the row filter

• Shift + Alt + Arrow right to group by the active column

• Shift + Alt + Arrow left ungroup the active column (remove it from the group by criteria)

• Alt + Arrow right expands a collapsed multi-column header

• Alt + Arrow left collapses an expanded multi-column header

• Alt + Arrow down expands a collapsed multi-column header

• Alt + Arrow up collapses an expanded multi-column header

TODO

- Ctrl + Arrow left moves the column one time to the left - Ctrl + Arrow right moves the column one time to the right - Ctrl + I to pin the column where the activation is (header or body cell doesn't matter) - Alt + I to pin the row where the activation is in the grid body - Alt + 0 to hide a visible column

Common grid scenarios

• Select a cell from row view and scroll down in order to hide it from the visible view -> press shift + tab, will put active state to the header of the column of which we've selected the grid cell -> press tab again, it won't scroll into the view where we started from, rather will put in active state the first cell of the current column.

• Continuous arrows press scrolls the grid view container.

Integration with other features

GroupBy (see specification) - On grid context entering we will navigate first through the Grouping chips via Arrow left/right.

• Ctrl + Arrow left moves the chip in the group by area one item left as long as it is not the first chip - then nothing will happen

• Ctrl + Arrow right moves the chip in the group by area one item right as long as it is not the last chip - then nothing will happen

• Ctrl + Arrow up sorts the active grouped column in ASC order

• Ctrl + Arrow down sorts the active grouped column in DSC order

• Tab activates the first header cell in the top header row

If the grouping row is focused, Arrow left/right won't work. Expand and Collapse behavior remains the same, with Ctrl + Arrow down/left will expand and Ctrl + Arrow up/right will collapse. Navigating from the grouping row to a cell in the row below will happen via Arrow down and to a cell in the row above via Arrow up. This is how you activate the grouping row as well.

• Alt + Arrow right expands a collapsed group row

• Alt + Arrow down expands a collapsed group row

• Alt + Arrow left collapses an expanded group row

• Alt + Arrow up collapses an expanded group row

**Notes: **

• When navigating with tab key press, the active style will go from the column header to the first fully visible element - group row or cell. If multiple grouped rows are present, the active state will be set to the first group row.
• Shift + tab will put back the active style to the header.

Pinning and Moving - The active element will change if a column is moved or pinned/unpinned.

Editing Specification - Enter key will put the cell in edit mode, Escape key will escape it. With Tab keypress the next editable cell will be put in edit mode. On cell editing (when we reach the last editable cell of the tbody) the cell will be submitted and next Tab stop element will be reached ().

Filtering Specification - Ctrl + Shift + L on the filter header will put the column in row filter mode, Escape key will escape it. With Tab keypress the next element in the filter row will be focused. On the last element in the row filter, it will be confirmed and the next Tab stop element will be reached.

• Arrow up will activate the header above the row filter UI for the column for which the row filter is shown.

• Arrow left with active header changes the context of the row filter to the column on the left.

• Arrow right with active header changes the context of the row filter to the column on the right.

• Tab on an active header cell activates the row filter and focuses the input.

• Arrow down on an active header cell activates the row filter and focuses the input.

Summaries - The first summary cell is focused on. With shift + tab you go back to tbody. Arrow keys for active element navigation. Home and end are working as expected.

If the first summary cell is active, on shift + tab the active state would be set to the first fully visible cell (row, if there is row grouping) and not the last active cell from which the summary was entered.

Paginator - If we have paging, we focus the pager focusable elements via tab.

Multi-column headers - we navigate through the child headers and header cells with the right/left/up/down arrows.

• Tab moves active state to the first body cell in the top row

• Arrow down moves active state to the cell in the first row of the same column

Note: If parent group header is active, the tab key press will navigate to the first cell part of the first real column.

Master-detail grid - we expand/collapse rows like for all other expandable items and treat the details section as one activate-able element similar to a group row.

• Alt + Arrow right expands a collapsed group row no matter which cell of the master is active

• Alt + Arrow down expands a collapsed group row no matter which cell of the master is active

• Alt + Arrow left collapses an expanded group row no matter which cell of the master is active

• Alt + Arrow up collapses an expanded group row no matter which cell of the master is active

• Arrow down on expanded master activates its details

• Arrow down on active details makes cell from the master row below active

Add new row

• Alt + plus key to add a row

• Alt + Shift + plus key to add a child row

Note: When having the action strip bar - tab sequence will go through all the action buttons part of the action strip as well.

Row Editing

The tab navigation will cycle though the row editable cells and action (cancel and done) buttons till the row editing is submitted or canceled.

Cell Editing

Cell in edit mode, the tab navigation will go through all editable cells, till the last editable cell is reached. Then it will go to the next tab stop (summaries area, paging area etc.)

Multi-row layout

• Tabbing into the Grid row view will set in active state the first fully visible cell (MRL cell, fully visible)

• If the active cell is grid-row-start: 2; grid-column-start: 1, tab press will set active the cell that corresponds to row-start:2 and column:start:1.

API

• GridKeydown to be deprecated - now we propagate this on Grid level and the user can handle keydown event to perform any custom logic.
• To add getter focused

Events

• focus and blur are removed

Aria compliance

• Grid has four main tab stops - header, tbody summary and footer.
• aria-describedby - The aria-describedby attribute is used to indicate the IDs of the elements that describe the Summary object. It is used to establish a relationship between widgets or groups and text that described them.
• aria-activedescendant - used to track a "virtual" focus. The aria-activedescendant property identifies the ID of the descendent element that currently has the virtual focus. (Example: return this.gridAPI.grid.id + '_' + activeElem.row + '_' + activeElem.column.

4.5. API

IgxGridCellComponent

Inputs

Name	Type	Description
column	IgxColumnComponent
row	any
cellTemplate	TemplateRef	Use Angular template syntax to manage the content of the cell
value	Used to set a new value on updating	any

Methods

Name	Description
selected	Get/set if cell is selected
focused	Get/set if cell is focused
width	Get cell width
styleClasses	Get cell classes
describedby	Get attr.aria-describedby
readonly	Get if cell is readonly
inEditMode	Get if cell is in edit mode, return type bool
nativeElement	Get html element nativeElement reference
columnIndex	Get cell's column index
rowIndex	Get cell's row index
grid	Get reference to the Grid, return type IgxGridComponent
gridID	Get grid's ID
template	Get cell template, return type TemplateRef<any>
context	Return cell context - cell value and cell reference
formatter	Get column formatter, return type any

HostListener

Name	Description
dblclick	Double click event
focus	On focus event
blur	On blur event
keydown.arrowleft	On arrow left press event
keydown.control.arrowleft	On ctrl + arrowLeft press event
keydown.arrowright	On arrow right press event
keydown.control.arrowright	On ctrl + arrowRight press event
keydown.arrowup	On arrow up press event
keydown.arrowdown	On arrow down press event
keydown.enter	On enter key press event, enter edit mode
keydown.f2	On F2 key press event, enter cell edit mode
keydown.escape	On escape key press, exit cell edit mode

IgxColumnComponent

Inputs

Name	Description	Type
field	Data source field name	string
header	Header text value	string
sortable	Enables the sorting feature of the column	bool
editable	Enables the editing feature of the column	bool
filterable	Enables the filtering feature of the column	bool
hidden	Enables the hiding feature of the column	bool
width	Set column width	string
headerClasses	Add styles to the header	string
cellClasses	Add classes to the cell	object
cellStyles	Add styles to the cell	object
rowClasses	Add classes to the row	object
rowStyles	Add styles to the row	object
index	Set column index - order	number
formatter		any
filteringCondition	Set filtering condition - contains, startsWith, endsWith, doesNotContain, equals, doesNotEqual, null, notNull, empty, notEmpty	STRING_FILTERS enumeration
filteringIgnoreCase	Capital and lower-case letters distinguishing for filtering value	bool
sortingIgnoreCase	Capital and lower-case letters distinguishing for sorting value	bool
dataType	Set type of the column - string, number, boolean, date	DataType enumeration

Methods

Name	Description
bodyTemplate	Get/set body template
headerTemplate	Get/set header template
footerTemplate	Get/set footer template
inlineEditorTemplate	Get/set inline editor template

IgxGridComponent

Inputs

Name	Description	Type
data	Set data source to the grid	collection
autoGenerate	Auto-generate columns	bool - default value false
id	ID of the Grid, the structure is igx-grid-${NEXT_ID++}	string
filteringLogic	Filtering logic of the Grid - values And, Or	FilteringLogic enumeration
filteringExpressions	Get/set filtering expression object - structure fieldName, condition, searchVal and ignoreCase	interface
paging	Enables the paging feature of the grid	bool
page	Get/set initially loaded page number	number
perPage	Get/set number of records rendered per page	number - default value 15
paginationTemplate	Set template syntax to manage the content of the cell	string
height	Set Grid height	number
width	Set Grid width	number
evenRowCSS	CSS applied to even Grid rows	string - default value is empty string
oddRowCSS	CSS applied to odd Grid rows	string - default value is empty string
rowHeight	Set row height	number - default value '50'
sortingExpressions	Set sorting expressions
columnWidth	Set default column width	string - default value is null.
isLoading	Sets if the grid is waiting for data	bool - default value false
showGroupArea	Set/get whether the group area row is shown	bool - default value true

Outputs

Name	Description
Event emitters	Notify for a change
onSelection	Used on cell selection, emits after selection has been made.
onColumnInit	Used on column initialization, emits before column is initialized.
onSortingDone	Used on column sorting, emits after sorting has been done.
onFilteringDone	Used on column filtering, emits after filtering has been done.
onPagingDone	Used on grid paging, emits after loading of a new page has been done.
onRowAdded	Used on row adding, emits after new row has been added to the grid.
onRowDeleted	Used on row deleting, emits after row has been deleted from the grid.
onDoubleClick	Used on cell double clicking, emits when cell has been double clicked from the grid.
onContextMenu	Used on cell right clicking, emits when cell has been right clicked from the grid.
onColumnResized	Used when column is resized, emits when column has been resized from the grid.
onColumnPinning	Used when column is pinned or unpinned through grid API, emits when cell has been pinned or unpinned from the grid API.
onRowSelectionChange	Used when row selection has changed, emits when the row selection has been changed.
onCellClick	Used on cell clicking, emits when cell has been clicked from the grid.
onScroll	Emitted when grid is scrolled vertically or horizontally.
activeNodeChange	Emitted when the active node of the grid is changed.

Changes as of February 2nd, 2021:

⚠ Behavioral changes 🆕 New stuff

Еvent	Interface
sorting 🆕	ISortingEventArgs 🆕
filtering 🆕	IFilteringEventArgs 🆕
onPaging 🆕	IPagingEventArgs🆕
onColumnPinning ⚠	IPinColumnCancellableEventArgs 🆕
columnVisibilityChanging 🆕	IColumnVisibilityChangingEventArgs 🆕
columnResizing 🆕	IColumnResizingEventArgs 🆕
onColumnMovingStart	IColumnMovingStartEventArgs
onColumnMoving	IColumnMovingEventArgs
onSortingDone	ISortingExpression | Array
onFilteringDone	IFilteringExpressionsTree
onPagingDone ⚠	IPageEventArgs
columnPinned 🆕	IPinColumnEventArgs
onColumnVisibilityChanged	IColumnVisibilityChangedEventArgs
onColumnResized	IColumnResizeEventArgs
onColumnMovingEnd	IColumnMovingEndEventArgs

Notes: All '-ing' events interfaces will extend IBaseEventArgs and CancelableEventArgs ⚠ Behavioral changes:

• pageChange is now hidden, and exposes a message to use onPagingDone instead.
• onPagingDone will be emitted AFTER the operation has completed
• onColumnPinning to emit IPinColumnCancellableEventArgs, instead of IPinColumnEventArgs. isPinned in both "ing" and "ed" events will contain the current pin state of the column.

IgxGridRowComponent

Inputs

Name	Description	Type
rowData		any[]
index		number
gridID		string
virtDirRow		IgxForOfDirective
cells		QueryList
tabindex		number - default value is '0'

Methods

Name	Description
focused	Get/set row focus
columns	Get all visible grid columns
grid	Get Grid reference
nativeElement	Get html element nativeElement reference

IgxGridHeaderComponent

Inputs

Name	Description	Type
column		IgxColumnComponent
gridID		string

Methods

Name	Description
width	Get header width

IgxGridFilterComponent

Inputs

Name	Description	Type
column		IgxColumnComponent

Methods

Name	Description
value	Get/set filtering value
dataType	Get column data type
conditions	Get DataType conditions, string, number, boolean, date
filter	Filter data
isActive	Check if filter condition is active, receive one parameter
clearFiltering	Clears value filter and filtering condition

5. ARIA Support

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 Grid has been designed so that it follows these guidelines.

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

• tabindex attribute allows access to the elements through the use of TAB and SHIFT + TAB keys.
• The Grid is decorated with a grid role.
• aria-selected attributes indicates when the selection feature is enabled.
• aria-describedby set attributes with a value set to the id of the corresponding grid and column field that belongs to. format gridID_columnField.
• aria-readonly attribute is used when certain cells are not editable.
• each grid header component has id attribute in format gridID_columnField.

5. Assumptions and Limitations

Known Limitations

Limitation	Description
Column widths set in percentage and px	Currently we do not support mixing of column widths with % and px.
When trying to filter a column of type number	If a value different than number is entered into the filtering input, NaN is returned due to an incorrect cast.
Grid width does not depend on the column widths	The width of all columns does not determine the spanning of the grid itself. It is determined by the parent container dimensions or the defined grid's width.
Grid nested in parent container	When grid's width is not set and it is placed in a parent container with defined dimensions, the grid spans to this container.
Grid OnPush ChangeDetectionStrategy	The grid operates with ChangeDetectionStrategy.OnPush so whenever some customization appears make sure that the grid is notified about the changes that happens.
Columns have a minimum allowed column width. Depending on the displayDensity option, they are as follows: "compact": 24px "cosy": 32px "comfortable ": 48px	If width less than the minimum allowed is set it will not affect the rendered elements. They will render with the minimum allowed width for the corresponding displayDensity. This may lead to an unexpected behavior with horizontal virtualization and is therefore not supported.
Row height is not affected by the height of cells that are not currently rendered in view.	Because of virtualization a column with a custom template (that changes the cell height) that is not in the view will not affect the row height. The row height will be affected only while the related column is scrolled in the view.
Remote virtualization works only for rows and not for columns	The remote virtualization for columns is not implemented.

6. Test Scenarios

Automation

Basic

• Only the visible items are rendered in the grid.
• Correct data chunk is rendered when scrolling vertically/horizontally.
• Keyboard navigation via arrow keys allows navigating vertically/horizontally outside of the current visible view port.
• Horizontal scrolling and navigation allows viewing the columns in grid with variable widths.
• Vertical/horizontal scrollbar renders when items exceed the available grid width/height.
• Vertical/horizontal scrollbar does not render when items fit the available grid width/height.There are no white spaces left where the scrollbar would be.
• When grid width/height is in pixels/percentage/not set horizontal/vertical scrollbar renders correctly, scrolling renders the correct chunk of data and keyboard navigation works.
• When grid width/height are set to null then virtualization is disabled - all records/columns are rendered.
• When grid has width/height in % and the window is resized horizontal/vertical virtualization works as expected.
• Changing the data runtime is applied and rendered correctly in virtual grid.
• Changing the columns runtime is applied and rendered correctly in virtual grid.
• Setting a different rowHeight is applied to all rows and vertical virtualization works as expected.

Integration Scenarios

• Sorting

  • After sorting is applied vertical virtualization works as expected. The new chunks of data loaded while scrolling reflect the correct sorted data.
  • After sorting a column, scrolling vertically out of its view and then returning back to it persists its sorted state. Sorted state is not incorrectly transferred to another column.

• Filtering

  • After data is filtered vertical scrolling works as expected. Filtered records are virtualized and you can scroll through them.
  • After filters are removed vertical scrolling works as expected.
  • If a filter is open for a column, scrolling horizontally will close the filter.
  • After data is filtered, scrolling horizontally out of the filtered column's view and then returning back to it persists its filtered state. State is not incorrectly transferred to another column.

• Editing

  • You can enter edit mode for a cell in virtual grid and the displayed value matches the cell value.
  • Editing ends when you start scrolling.
  • Changes done via the editor are persisted when you scroll horizontally/vertically out of view and then return again.
  • Vertical scrolling works after adding/removing records runtime.

• Paging

  • Horizontal/vertical virtualization works in grid that also has paging enabled. The current page data is virtualized.

• Templates

  • If cells/headers/footers are templated that the templates are properly updated with the new data when you scroll vertically/horizontally.

• Row and Cell Selection

  • After row is selected horizontally/vertically scrolling persists the selection.
  • Select/deselect via the header row selector is applied to all rows, including those outside of the current view.
  • Header row selector is updated when selecting/deselecting rows in the grid and scrolling horizontally/vertically persist that state.
  • Cell selection works by clicking/tapping on a grid cell.
  • Keyboard navigation with the arrow keys allows navigating from the start to the end of the grid cells/rows.

• Column hiding

  • Hidden columns are not displayed in virtual grid.
  • Hidden columns that have width don't affect the grid's horizontal scrolling.
  • Hiding columns runtime does not break horizontal scrolling.
  • Horizontal scrollbar is updated when columns are hidden/shown and horizontal scrolling works as expected.

• Column pinning

  • Pinned column cell are updated correctly when vertically scrolling through the data.
  • Horizontal scrollbar is displayed under the unfixed area.
  • Keyboard navigation works when moving from pinned to unpinned area and vice versa.
  • Horizontal scrollbar is updated when columns are pinned/unpinned and horizontal scrolling works as expected.

• Column moving

  • Keyboard navigation works as expected after column's order is changed.
  • Horizontal virtualization works as expected after column's order is changed.

• Column Summaries

  • Vertical scrolling works as expected when summaries are enabled.
  • Summaries summarize whole data when grid is virtualized.
  • Summaries are synched with the content and headers when horizontally scrolling.
  • Summaries show for correct column when horizontally scrolling and changing the visible columns.
  • Summaries have same height when scrolling horizontally through columns that have different summaries count.

• Column resizing

  • After dynamically resizing columns horizontal virtualization works as expected.
  • After resizing column, scrolling that column out of view and then returning to it, its new width is persisted.

• igxTabs

  • igxGrid is rendered correctly when initialized in non active tab
  • igxGrid is rendered correctly when initialized in non active tab with different dimensions and features enabled

API and Events

• Events
  • onDataPreLoad event is fired before requesting a new chunk of data. Its parameters are correct and it can be used to implement remote virtualization in the grid.

Manual

Basic

• Grid vertical/horizontal scrollbar is visible and reflects the actual data size.
• Grid can scroll up/down/left/right via the scrollbar, via the mouse wheel and via touch interactions.
• There are no misalignment between header/content/footer cells when scrolling horizontally/vertically.
• Last row/column can be scrolled into view with different height/width (%, px, none set) and rowHeight/columnWidth settings.

7.2. Auto-Sizing

1. Default rendering of data with 5 columns and 5 rows.
2. Default rendering of data with 10 columns and 30 rows.
3. Default rendering of data with 30 columns and 1000 rows.
4. Default rendering of data with 150 columns and 20000 rows.
5. Rendering of data with 5 columns and 5 rows where 2 of the columns have width set.
6. Rendering of data with 5 columns and 30 rows where 3 of the columns have width set.
7. Rendering of data with 30 columns and 1000 rows where 5 of the columns have width set.
8. Rendering of data with 150 columns and 20000 rows where 5 of the columns have width set.

Define new defaults for grid width/height:

width

• 100% - the grid should, by default, be spanning the container it's placed in.
• null - the grid should grow horizontally according to it's content, making all the content visible and not displaying a scrollbar in its container.

columnWidth

• null by default. The grid should be inferring from the number of columns and the container it's placed in, what the default column width should be set to.
• the grid should span all of its columns within the grid body, but not allowing columns to go below a certain width by default. The minimum width can be set to 136px, which is 10 columns displayed within a screen size of 1366px.
  • e.g.
    • 5 columns in a 1600px wide viewport should be displayed by each column being 320px wide.
    • 15 columns in a 1600px wide viewport should be displayed with a horizontal scrollbar and each column will be 136px wide - this will also be virtualized.
• when some, but not all, of the columns have explicit width set, and there's no defaultWidth provided, then the same calculations should be applied, but taking into account the width set for the columns with provided configuration.
  • e.g.
    • 5 columns in a 1600px wide viewport, with two of the columns set at 500px width, should be displayed by each column being 200px wide, except for the two that are 500px wide.
    • 15 columns in a 1600px wide viewport, with two of the columns set at 500px width, should be displayed with a horizontal scrollbar and each column will be 136px wide, except for the two that are 500px wide - this will also be virtualized.

height

1. Height is set in px => Grid renders with the specified height.

2. Height in set in % or no height is set (which defaults to height=100%).

   • Can resolve height. => Grid renders with the resolved height in px. In case browser is resized – recalculate based on new sizes.

   • Cannot resolve height (ex. container has no height, container is hidden etc.). => Calculate and set default body height on data change based on data:

     • No data (0 data records) => Grid renders with height of headers/footers + the height of the ‘No records’ template for the content.

     • Some data (data records less than 10) => Grid renders with height of headers/footers + number of records * rowHeight for the content.

     • Large data (data records more than 10) => grid renders with height of headers/footers + 10 * rowHeight for the content.

3. Height is set to null => All records are rendered. Grid renders with height of headers/footers + the height all records for the content.

Keyboard navigation scenarios

Keyboard interactions

• Arrow Key Up to navigate one cell up (no wrapping).
• Arrow Key Down to navigate one cell down (no wrapping).
• Arrow Key Left to navigate one cell left (no wrapping between lines) on the current row only.
• Arrow Key Right to navigate one cell right (no wrapping between lines) on the current row only.
• Page Up scroll one page (view port) up.
• Page Down scroll one page (view port) down.
• [DEPRECATED] Tab move the selection to next cell or next row if the last cell is reached (without row selection).
• [DEPRECATED] Shift + tab move the selection to previous cell or previous row (last row cell) if the first cell is reached.
• Ctrl + Arrow Key Up move to top cell in column.
• Ctrl + Arrow Key Down 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.

Header Keyboard navigation

Base Tests:

• Verify when focusing on grid header that the first header cell is selected. When pressing Tab key the first grid cell should be selected.
• Verify that when pressing Tab key from the grid body the first header is selected. Test with scrolls and without scrolls.
• Test that headers can be activated (active style) with the right and left arrow keys
• Test navigating to the first/last header with Home/End and Ctrl + Arrow Left/Right

Integration:

• MCH: Verify navigating with arrow keys on grouped rows. Verify that only grouped header is active.
• MCH: verify selecting children and parent with Up and Down Arrow keys
• MCH: Verify navigation with arrow keys in the child rows.
• MCH: Verify expand and collapse groups with Alt + arrow keys up/down and left/right
• MCH: Verify navigation with Home and End keys
• MRL: Verify navigation with Left and Right Arrow keys through header cell
• MRL: Verify selecting different cells with Up and Down Arrow keys.
• MRL: Verify navigation with Home and End keys
• Filtering: Verify opening the excel style filter with keys Ctrl + Shift + L
• Filtering: Verify opening the filter row with keys Ctrl + Shift + L. verify headers navigation when the filtering row is opened
• Advanced Filtering: verify opening the Advanced Filter with keys Alt + L
• Sorting: Verify sorting can be performed with the keys Ctrl + Arrow up/down. Test to sort non-sortable column.
• Group by: Verify that the column can be grouped with the keys Shift + Alt + Arrow right. Test trying to group non-groupable column.
• Group by: verify that the column can be ungrouped with the keys Shift + Alt + Arrow left. Test when the column is not grouped, when it is g=first grouped column and when it is second grouped column.
• Column selection: When column selection is single, verify selecting a column with space key
• Column selection: When column selection is multiple, verify selecting multiple columns with space key. Verify selecting columns and shift+space
• Pinning: Verify headers navigation when there are pinned columns. Test also home and end keys. Test Tab from the header to the grid body.

Integration Scenarios

• Grouping

  • Select the last cell in the last grid row of grouped area. Press Tab key, the grouped row should be focused. Press Alt + Left/right arrow keys to expand/collapse grouped row.
  • Select the first grouped row with the mouse and press Tab key. Cell selection should move to the first row cell (of the first row in the grouped area rows).
  • Select the second grouped row with the mouse and press Shift + Tab key. Cell selection should move in the last cell row (of the last row cell in the grouped area rows).
  • Select the first row cell (of the first row in the second grouped area rows) Shift + tab should select the second group row in the grid. Press Alt + Left/right arrow keys to expand/collapse grouped row.
  • When grouped row is selected with tab navigation and Right arrow key is pressed, the grouped row should be expanded. On Left arrow key the grouped row should be collapsed. (Special class will be applied to the grouped row to indicate focus).
  • When grouped row is selected with mouse click and Right arrow key is pressed, the grouped row should be expanded. On Left arrow key the grouped row should be collapsed. (Special class will be applied to the grouped row to indicate focus).
  • Select first cell of the first row in a grouped area. Press Arrow Key Up and the focus should be moved to the first group row (Special class will be applied to the grouped row to indicate focus). Currently selected cell should remain selected. Press Alt + Left/right arrow keys to expand/collapse grouped row.
  • Select first cell of the last row in a grouped area. Press Arrow Key Down and the focus should be moved tp the first group row (Special class will be applied to the grouped row to indicate focus). Currently selected cell should remain selected. Press Alt + Left/right arrow keys to expand/collapse grouped row.

• Pinning

  • Tab/Arrow keys should navigate correctly when we have 2 pinned columns, should include the pinned area as well, when selection a cell.

• Editing Specification.

• Scrolling - On navigation with the left arrow key press the scroll should move with the cell selection, till the end of the grid. (same as right key press)

• igxDialog

  • igxGrid is rendered correctly when initialized in non visible igxDialog (with different dimensions and features enabled)