Public Cell API Specification

Revision History

Version	User	Date	Notes
0.1	Hristo Anastasov	July 14, 2021	Initial Draft
0.2	Hristo Anastasov	July 16, 2021	API revision

1. Task

Currently, grid APIs which return "cell objects" are returning the actual cell component from current state of the DOM. However this is far from useful as with the current implementation virtualization state is not taken into account (#6158) as well as exposing API which should not be usable by users of the grid.

As a solution, a new cell-like interface should be exposed by the grids as the type returned from certain public API calls. This new interface will act as a façade for the core cell API (while also taking the current virtualization state into account.

2. Overview

IgxGridCell is a new class, which implement the new CellType interface. This class act as a façade for the corresponding cell components:

IgxGridCellComponent
IgxTreeGridCellComponent
IgxHierarchicalGridCellwComponent.

getCellByKey and getCellByColumn and getCellByColumnVisibleIndex now should not depend on what is there in the virtualization container.

Internal functionalities and tests that depend on the cells DOM elements are changed to use

gridAPI.get_cell_by_key
gridAPI.get_cell_by_index
gridAPI.get_cell_by_visible_index

Internal functionalities and tests that depend on the cells public API, continue use the public

getCellByColumn
getCellByColumnVisibleIndex
getCellByKey

const cell: CellType = grid.getCellByColumn(rowIndex, field);
const cell: CellType = grid.getCellByKey(rowID, field);
const cell: CellType = grid.getCellByColumnVisibleIndex(rowIndex, columnIndex);
const rowCells: CellType[] = row.cells;
const columnCells: CellType[] = column.cells;

3. Implementation

Declare the public CellType interface, which defines the public properties/methods to be exposed in the public API.

export interface CellType {
	value: any;
	editValue: any;
	selected: boolean;
	editable: boolean;
	editMode: boolean;
	column: IgxColumnComponent;
	row: RowType;
	grid: IgxGridComponent | IgxTreeGridComponent | IgxHierarchicalGridComponent;
	cellID: { rowID: any; columnID: number; rowIndex: number };
	width: string;
	update?: (value: any) => void;
}

Implement the new façade classes, which should implement the interface. This façade class takes the row index and column field as parameters in the constructor, along with the corresponding grid component.

IgxGridCell implements the interface CellType.

export class IgxGridCell implements CellType {
	constructor(
		grid: IgxGridBaseDirective | IgxGridComponent | IgxTreeGridComponent | IgxHierarchicalGridComponent,
		row: number | RowType,
		column: string | IgxColumnComponent);

	public get row(): RowType {
		return this._row || this.grid.createRow(this._rowIndex);
	}

	public get column(): IgxColumnComponent {
		return this._column || this.grid.getColumnByName(this._columnField);
	}
  ...
}

Make the public cell API’s work with instances of the new classes. Those instances are created on demand in corresponding calls:

    public getCellByColumn(rowIndex: number, columnField: string): CellType {
        const row = this.getRowByIndex(rowIndex);
        const column = this.columnList.find((col) => col.field === columnField);
        if (row && row instanceof IgxGridRow && column) {
            return new IgxGridCell(this, rowIndex, columnField);
        }
    }

    public getCellByKey(rowSelector: any, columnField: string): CellType {
        const row = this.getRowByKey(rowSelector);
        const column = this.columnList.find((col) => col.field === columnField);
        if (row && column) {
            return new IgxGridCell(this, row.index, columnField);
        }
    }

    @DeprecateMethod('`getCellByColumnVisibleIndex` is deprecated. Use `getCellByColumn` or `getCellByKey` instead')
    public getCellByColumnVisibleIndex(rowIndex: number, index: number): CellType {
        const row = this.getRowByIndex(rowIndex);
        const column = this.columnList.find((col) => col.visibleIndex === index);
        if (row && row instanceof IgxGridRow && column) {
            return new IgxGridCell(this, rowIndex, column.field);
        }
    }

4. Limitations

If at the given index there is a row different from data row, cell API will return undefined.

5. Behavioural changes

getCellByColumn will now return an instance of IgxGridCell
getCellByKeywill now return an instance of IgxGridCell
getCellByColumnVisibleIndex will now return an instance of IgxGridCell, but is deprecated and will be removed in further versions.

6. Test plan

There are currently many tests for all grids that use getCellByKey, getCellByColumn and getCellByColumnVisibleIndex and row.cells public APIs. Many of them verify correct rendering of the DOM elements, the rest of them verify the cell public API usage.

Those that verify the correct DOM rendering, need to be rewritten to use the gridAPI.get_cell_by_key or gridAPI.get_cell_by_index or gridAPI.get_cell_by_visible_index.
Those that verify the usage of the public API, continue to use the getCellByKey, getCellByColumn and getCellByColumnVisibleIndex and row.cells. Some of them cast the type returned as IgxGridCellComponent, those casts need to be removed.

Test cases to be added:

Test	Should verify
use `getCellBy` to get a cell that is out of the virtualized dom container	cell is returned
use `getCellBy` to get a cell that is first or last	cell is returned
use `getCellBy` to get a cell whose row index exceeds last index of the current page	cell returned
use `getCellBy` with a row index that is on different grid pages	cell retured
use `getCellBy` to take a record, which is on another grid page	returns undefined
use `getCellBy` at a row index, where the row is not a data row (i.e. IgxSummaryRow, igxGroupByRow, A detail row)	returns undefined
use `cell.row` for different grid	returns respective type of IgxGridRow, IgxTreeGridRow or IgxHierarchicalGridRow
Test the cell API	Updates the corresponding state properly i.e. cell.setEditMode(val) = enters/exits the edit mode