The identifier for one of the areas: header, body, footer. This property determines which area of the table this model represents.
// Creating an area model for the header
const headerModel = new AreaModel();
headerModel.areaIdent = "header";
// Checking which area a model represents
if (areaModel.areaIdent === "body") {
// This is a body area model
}
A model and controller for row checkbox selection. This property allows the area to support row selection via checkboxes.
// Creating a checkbox model for row selection
import { CheckboxModel } from "@guiexpert/table";
const bodyModel = new AreaModel();
bodyModel.areaIdent = "body";
bodyModel.rowSelectionModel = new CheckboxModel();
// Later, check if a row is selected
const isSelected = bodyModel.isRowChecked(5);
Optional canOptional (row drag, managed mode): true if the rows can be moved to the target – e.g. false for a node dropped into its own child, or while a filter hides rows. Without moveRows the table cannot move rows itself.
display indices of the dragged rows (ascending)
the drop target (display index before the move)
true if moveRows would move them
class TasksBodyModel extends AreaModel {
tasks: string[] = ["Write", "Test", "Ship"];
override getRowCount(): number { return this.tasks.length; }
override getValueAt(rowIndex: number): any { return this.tasks[rowIndex]; }
canMoveRows(rowIndices: number[], target: RowDropTargetIf): boolean { return target.position !== "inside"; }
moveRows(rowIndices: number[], target: RowDropTargetIf): boolean {
return moveArrayItems(this.tasks, rowIndices, getInsertBeforeIndex(target)) > -1;
}
}
1.1.95
Changes the order of columns by moving a column from one position to another. This method is called when the user drags a column to a new position.
The index of the column to move
The index where the column should be moved to
// Move the second column (index 1) to the fourth position (index 3)
areaModel.changeColumnOrder(1, 3);
// Implementation example
changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void {
// Move the column in the internal data structure
this.arrayMove(this.columns, sourceColumnIndex, targetColumnIndex);
// Update any dependent data structures
this.arrayMove(this.cellRenderers, sourceColumnIndex, targetColumnIndex);
}
Sorts the rows in this area based on the provided sort items. This method is called when the user clicks on a sortable column header.
An array of sort items, each containing a column index and sort direction
True if sorting was performed, false otherwise
// Sort by the second column in ascending order
bodyAreaModel.doSort([{ columnIndex: 1, sortState: 'asc' }]);
// Sort by the first column in descending order, then by the second column in ascending order
bodyAreaModel.doSort([
{ columnIndex: 0, sortState: 'desc' },
{ columnIndex: 1, sortState: 'asc' }
]);
// Implementation example: a body model that sorts its own rows
class MyBodyModel extends AreaModelObjectArray<any> {
override doSort(sortItems: SortItem[]): boolean {
if (!sortItems.length) return false;
// Apply sorting to the rows
for (const sortItem of sortItems) {
const { columnIndex, sortState } = sortItem;
const property = this.columnDefs[columnIndex].property;
const direction = sortState === 'asc' ? 1 : -1;
this.rows.sort((a, b) => {
const valueA = a[property];
const valueB = b[property];
if (valueA < valueB) return -1 * direction;
if (valueA > valueB) return 1 * direction;
return 0;
});
}
return true;
}
}
Applies a filter function to the rows in this area. This method is called when a filter is applied to the table.
A function that takes a row and returns true if the row should be visible
// Filter rows where age > 30
bodyAreaModel.externalFilterChanged(row => row.age > 30);
// Clear all filters
bodyAreaModel.externalFilterChanged(() => true);
// Implementation example
externalFilterChanged<T>(predictFn: FilterFunction<T>): void {
// Apply the filter to the rows
this.filteredRows = this.rows.filter(predictFn);
}
Returns a cell renderer for the cell at the specified row and column indices. A cell renderer is responsible for rendering the cell content in a custom way. If undefined is returned, the cell value will be rendered directly.
The index of the row
The index of the column
A cell renderer instance, or undefined for default rendering
// Get a custom renderer for a cell
const renderer = bodyAreaModel.getCellRenderer(1, 2);
// Implementation example using column definitions
getCellRenderer(rowIndex: number, columnIndex: number): CellRendererIf | undefined {
// Get renderer from column definition
const columnDef = this.columnDefs[columnIndex];
return columnDef?.rendererMap?.[this.areaIdent];
}
Returns the column span value for the cell at the specified row and column indices. A colspan value of N means the cell spans N columns horizontally. Values less than 2 are ignored (no spanning).
The index of the row
The index of the column
The colspan value (number of columns the cell spans)
// Check if a cell spans multiple columns
const colspan = headerAreaModel.getColspanAt(0, 0);
if (colspan > 1) {
console.log(`This header cell spans ${colspan} columns`);
}
// Implementation example for a model with column spanning
getColspanAt(rowIndex: number, columnIndex: number): number {
// Special case: first row, first column spans 3 columns
if (rowIndex === 0 && columnIndex === 0) return 3;
// No spanning for other cells
return 1;
}
Optional getReturns the row height if all rows of this area have the same height, otherwise undefined.
The renderer uses this value to find the first visible row directly instead of summing up the heights
of all rows above it – with millions of rows this keeps scrolling at the end of the table as fast as at
the beginning. Only return a number if getRowHeight(i) returns exactly this value for every row.
If the method is missing or returns undefined, the renderer falls back to iterating the row heights.
The constant row height in pixels, or undefined if row heights may vary.
// Custom area model with 34px rows:
getRowHeight(_rowIndex: number): number { return 34; }
getConstantRowHeight(): number | undefined { return 34; }
Returns an array of CSS class names to apply to the cell at the specified row and column indices. This method allows for custom styling of individual cells.
The index of the row
The index of the column
An array of CSS class names
// Apply custom classes to cells
const classes = bodyAreaModel.getCustomClassesAt(1, 2);
console.log(`Cell classes: ${classes.join(', ')}`);
// Implementation example with conditional styling
getCustomClassesAt(rowIndex: number, columnIndex: number): string[] {
const classes: string[] = [];
// Add classes based on row index
if (rowIndex % 2 === 0) {
classes.push('even-row');
} else {
classes.push('odd-row');
}
// Add classes based on cell value
const value = this.getValueAt(rowIndex, columnIndex);
if (typeof value === 'number' && value < 0) {
classes.push('negative-value');
}
// Add classes for selected rows
if (this.isRowChecked(rowIndex)) {
classes.push('selected-row');
}
return classes;
}
Returns an object containing CSS style properties to apply to the cell at the specified row and column indices. This method allows for inline styling of individual cells.
The index of the row
The index of the column
An object with CSS style properties, or undefined if no custom styles
// Apply custom styles to cells
const styles = bodyAreaModel.getCustomStyleAt(1, 2);
console.log('Cell styles:', styles);
// Implementation example with conditional styling
getCustomStyleAt(rowIndex: number, columnIndex: number): { [key: string]: string } | undefined {
// Apply background color based on value
const value = this.getValueAt(rowIndex, columnIndex);
if (typeof value === 'number') {
// Color gradient based on value
if (value < 0) {
return { 'background-color': `rgba(255, 0, 0, ${Math.min(Math.abs(value) / 100, 0.5)})` };
} else if (value > 0) {
return { 'background-color': `rgba(0, 255, 0, ${Math.min(value / 100, 0.5)})` };
}
}
return undefined; // No custom styles
}
Optional getOptional: the input of a cell – what was typed, e.g. the formula text of a cell formula ("=B2*C2"), while
getValueAt gives its result (TableOptionsIf.cellFormulas). Editor, copy inside the table and undo
use it. Without it the input is the value. Implemented by the object-array and array models.
tableModel.getBodyModel().getInputValueAt?.(0, 3); // "=B2*C2"
1.1.99
Returns the maximum colspan value that can occur in this area model. This value is used to optimize rendering performance.
The maximum possible colspan value in this area
// Get the maximum colspan for optimization
const maxColspan = headerAreaModel.getMaxColspan();
// Implementation example
getMaxColspan(): number {
// If the model has no colspans, return 0 for optimization
return 0;
// If the model has colspans, return the maximum possible value
// return 3; // If some cells span up to 3 columns
}
Returns the maximum rowspan value that can occur in this area model. This value is used to optimize rendering performance.
The maximum possible rowspan value in this area
// Get the maximum rowspan for optimization
const maxRowspan = bodyAreaModel.getMaxRowspan();
// Implementation example
getMaxRowspan(): number {
// If the model has no rowspans, return 0 for optimization
return 0;
// If the model has rowspans, return the maximum possible value
// return 2; // If some cells span up to 2 rows
}
Returns the row object at the specified index. This method provides access to the underlying data structure.
The index of the row
The row object
// Get a row object
const row = bodyAreaModel.getRowByIndex(1);
console.log('Row data:', row);
// Implementation example for an array-based model
getRowByIndex(rowIndex: number): any {
if (rowIndex < 0 || rowIndex >= this.data.length) return undefined;
return this.data[rowIndex];
}
Returns the number of rows in this area. This is a fundamental method that determines the vertical size of the area.
The number of rows in the area
// Get the number of rows in the body area
const rowCount = bodyAreaModel.getRowCount();
console.log(`The body has ${rowCount} rows`);
// Implementation example for an array-based model
getRowCount(): number {
return this.data.length;
}
Returns the height of the row at the specified index, in pixels. This method allows for variable row heights in the table.
The index of the row
The height of the row in pixels
// Get the height of a row
const height = bodyAreaModel.getRowHeight(1);
console.log(`Row 1 height: ${height}px`);
// Implementation example with fixed row height
getRowHeight(rowIndex: number): number {
return this.defaultRowHeight; // e.g., 30px
}
// Implementation example with variable row heights
getRowHeight(rowIndex: number): number {
// First row is taller
if (rowIndex === 0) return 50;
// Rows with more content are taller
const row = this.getRowByIndex(rowIndex);
if (row && row.hasLongContent) return 60;
// Default height for other rows
return 30;
}
Optional getOptional: the value of a column for a row object – computed for a calculated column, otherwise the property path (TableApi.getRowValue). Implemented by the object-array, tree, row-group and pivot models.
tableModel.getBodyModel().getRowValue?.({ price: 25, quantity: 10 }, "total"); // 250
1.1.95
Returns the row span value for the cell at the specified row and column indices. A rowspan value of N means the cell spans N rows vertically. Values less than 2 are ignored (no spanning).
The index of the row
The index of the column
The rowspan value (number of rows the cell spans)
// Check if a cell spans multiple rows
const rowspan = bodyAreaModel.getRowspanAt(0, 0);
if (rowspan > 1) {
console.log(`This cell spans ${rowspan} rows`);
}
// Implementation example for a model with row spanning
getRowspanAt(rowIndex: number, columnIndex: number): number {
// Special case: first column spans 2 rows at the beginning
if (columnIndex === 0 && rowIndex % 2 === 0) return 2;
// No spanning for other cells
return 1;
}
Returns a string representation of the cell value at the specified row and column indices. This method is used when exporting the table data or copying to clipboard.
The index of the row
The index of the column
The text value of the specified cell
// Get the text value of a cell for export
const textValue = bodyAreaModel.getTextValueAt(1, 2);
// Implementation example
getTextValueAt(rowIndex: number, columnIndex: number): string {
const value = this.getValueAt(rowIndex, columnIndex);
// Handle different data types appropriately
if (value === null || value === undefined) return '';
if (value instanceof Date) return value.toISOString();
return String(value);
}
Returns the tooltip text for the cell at the specified row and column indices. This tooltip will be displayed when the user hovers over the cell.
The index of the row
The index of the column
The tooltip content (usually a string)
// Get the tooltip for a cell
const tooltip = bodyAreaModel.getTooltipAt(1, 2);
// Implementation example
getTooltipAt(rowIndex: number, columnIndex: number): any {
// Use the cell value as the tooltip
return this.getValueAt(rowIndex, columnIndex);
// Or provide a more detailed tooltip
// const value = this.getValueAt(rowIndex, columnIndex);
// return `Value: ${value}\nRow: ${rowIndex}\nColumn: ${columnIndex}`;
}
Optional getThe number of rows the area would show without the external filter. Optional: the table uses it to tell "No rows to show" (no rows at all) from "No matching rows" (the filter hides all rows) – see OverlayOptionsIf. Models without it always get "No rows to show".
e.g. all rows of an object array; for a tree the displayed rows before filtering
class OrdersBodyModel extends AreaModel {
private all: string[][] = [];
private shown: string[][] = [];
override getRowCount(): number { return this.shown.length; }
getUnfilteredRowCount(): number { return this.all.length; }
override getValueAt(rowIndex: number, columnIndex: number): any { return this.shown[rowIndex]?.[columnIndex]; }
}
1.1.92
Returns the value of the cell at the specified row and column indices. This is one of the most important methods in the area model, as it provides the actual data to be displayed in each cell.
The index of the row
The index of the column
The value at the specified cell
// Get the value of a cell
const value = bodyAreaModel.getValueAt(1, 2);
console.log(`Cell (1,2) contains: ${value}`);
// Implementation example for a 2D array model
getValueAt(rowIndex: number, columnIndex: number): any {
if (rowIndex < 0 || rowIndex >= this.data.length) return undefined;
const row = this.data[rowIndex];
if (columnIndex < 0 || columnIndex >= row.length) return undefined;
return row[columnIndex];
}
// Implementation example for an object array model
getValueAt(rowIndex: number, columnIndex: number): any {
const row = this.getRowByIndex(rowIndex);
if (!row) return undefined;
const property = this.columnDefs[columnIndex].property;
return row[property];
}
Returns the Y-coordinate (in pixels) of the top of the row at the specified index. This method is used for scrolling and positioning rows in the viewport.
The index of the row
The Y-coordinate of the top of the row, in pixels
// Get the Y-position of a row
const yPos = bodyAreaModel.getYPosByRowIndex(10);
console.log(`Row 10 starts at Y-position: ${yPos}px`);
// Implementation example with fixed row heights
getYPosByRowIndex(rowIndex: number): number {
return rowIndex * this.defaultRowHeight;
}
// Implementation example with variable row heights
getYPosByRowIndex(rowIndex: number): number {
// Use a pre-calculated array of Y-positions
return this.yPositions[rowIndex];
// Or calculate on-the-fly
// let yPos = 0;
// for (let i = 0; i < rowIndex; i++) {
// yPos += this.getRowHeight(i);
// }
// return yPos;
}
Initializes the area model. This method is called internally by the TableModel during initialization. It can be used to perform any necessary setup, such as calculating row positions.
// Implementation example
init(): void {
// Calculate y-positions for all rows
this.calculateYPositions();
// Initialize any other internal state
this.initialized = true;
}
Optional invalidateOptional: drops cached, derived values (e.g. the totals of an AreaModelAggregateFooter). The table calls
it for all three areas when data may have changed: filter, sorting, editing, updateCells() and the public
tableApi.repaint() / repaintHard() – not on scrolling or internal repaints.
After an edit and updateCells() the table passes change (since 1.1.94): the area and the displayed rows that
changed – a model may recompute only what depends on them (AreaModelRowGroups recomputes the groups of
these rows). Without change anything may have changed.
Optional change: DerivedValuesChangeIfclass CachedTotalsFooter extends AreaModel {
private total?: number;
constructor(private readonly body: AreaModelObjectArray<Order>) {
super();
this.areaIdent = "footer";
}
invalidateDerivedValues(): void { this.total = undefined; }
override getRowCount(): number { return 1; }
override getValueAt(_row: number, _col: number): any {
return this.total ??= this.body.getFilteredRows().reduce((sum, o) => sum + o.total, 0);
}
}
1.1.94
Optional isOptional: true if the column with this property is calculated (ColumnDefIf.valueGetter / formula).
Implemented by the object-array, tree, row-group and pivot models.
tableModel.getBodyModel().isCalculatedProperty?.("total"); // true
1.1.95
Determines whether the cell at the specified row and column indices is editable. If true, the user can edit the cell content.
The index of the row
The index of the column
True if the cell is editable, false otherwise
// Check if a cell is editable
const editable = bodyAreaModel.isEditable(1, 2);
if (editable) {
console.log('This cell can be edited by the user');
}
// Implementation example using column definitions
isEditable(rowIndex: number, columnIndex: number): boolean {
// Get editability from column definition
const columnDef = this.columnDefs[columnIndex];
return columnDef?.editable?.() ?? false;
}
// Implementation example with conditional editability
isEditable(rowIndex: number, columnIndex: number): boolean {
// Header cells are not editable
if (this.areaIdent === 'header') return false;
// First column is not editable (e.g., ID column)
if (columnIndex === 0) return false;
// Other cells in the body are editable
return this.areaIdent === 'body';
}
Determines whether this area supports filtering. If true, the area can be filtered using the externalFilterChanged method.
True if the area is filterable, false otherwise
// Check if an area is filterable
const filterable = bodyAreaModel.isFilterable();
if (filterable) {
console.log('This area supports filtering');
}
// Implementation example
isFilterable(): boolean {
// Only the body area is filterable
return this.areaIdent === 'body';
}
Determines whether the row at the specified index is checkable. If true, a checkbox will be rendered at the beginning of the row.
The index of the row
True if the row is checkable, false otherwise
// Check if a row is checkable
const checkable = bodyAreaModel.isRowCheckable(1);
if (checkable) {
console.log('This row can be checked by the user');
}
// Implementation example
isRowCheckable(rowIndex: number): boolean {
// All rows are checkable by default
return true;
// Or implement custom logic
// const row = this.getRowByIndex(rowIndex);
// return row && !row.locked; // Only unlocked rows are checkable
}
Returns the checked state of the row at the specified index.
The index of the row
The checked state of the row (true, false, or 'indeterminate'), or undefined if the row is not checkable
// Check if a row is checked
const checkedState = bodyAreaModel.isRowChecked(1);
if (checkedState === "full") {
console.log('This row is checked');
} else if (checkedState === "semi") {
console.log('This row is partially checked');
}
// Implementation example using a row selection model
isRowChecked(rowIndex: number): CheckedType | undefined {
if (!this.rowSelectionModel) return undefined;
const row = this.getRowByIndex(rowIndex);
return this.rowSelectionModel.isRowChecked(row);
}
Optional isOptional: true for a cell that names its row (a label such as "Nord" or "Total") – the table gives it
role="rowheader" instead of gridcell, so screen readers announce it with the row.
class LabeledBody extends AreaModel {
isRowHeaderCell(_rowIndex: number, columnIndex: number): boolean { return columnIndex === 0; }
}
1.1.94
Determines whether the cell at the specified row and column indices is selectable.
If true, the user can select the cell: the table draws the selection only on selectable body cells.
All built-in models and AreaModel return true (except the hidden and cover-grid models).
The index of the row
The index of the column
True if the cell is selectable, false otherwise
// Check if a cell is selectable
const selectable = bodyAreaModel.isSelectable(1, 2);
if (selectable) {
console.log('This cell can be selected by the user');
}
// Implementation example
isSelectable(rowIndex: number, columnIndex: number): boolean {
// All cells are selectable by default
return true;
// Or implement custom logic
// return this.areaIdent === 'body'; // Only body cells are selectable
}
Optional moveOptional (row drag, managed mode): moves the rows to the target in the model – the table calls it on a drop and
for tableApi.moveRows(), then repaints. Implemented by AreaModelObjectArray, AreaModelArrayOfArrays and
AreaModelTree (in place in their row arrays). See canMoveRows for an example.
display indices of the dragged rows (ascending)
the drop target (display index before the move)
true if the rows were moved
1.1.95
Sets the checked state of the row at the specified index.
The index of the row
The new checked state
// Check a row
bodyAreaModel.setRowChecked(1, true);
// Uncheck a row
bodyAreaModel.setRowChecked(2, false);
// Implementation example using a row selection model
setRowChecked(rowIndex: number, checked: boolean): void {
if (!this.rowSelectionModel) return;
const row = this.getRowByIndex(rowIndex);
if (row) {
this.rowSelectionModel.checkRow(row, checked);
}
}
Sets the value of a cell at the specified row and column indices. This method is called when a cell is edited by the user or programmatically.
The index of the row containing the cell
The index of the column containing the cell
The new value to set
// Set the value of a cell
areaModel.setValue(1, 2, "New Value");
// Implementation example for an object-based model
setValue(rowIndex: number, columnIndex: number, value: any): boolean {
const row = this.getRowByIndex(rowIndex);
if (!row) return false;
const property = this.columnDefs[columnIndex].property;
row[property] = value;
return true;
}
Sorts the rows in this area using a custom comparator function. This method provides more flexibility than doSort for complex sorting logic.
Optional compareFn: ((a, b) => number)A function that compares two rows and returns a number:
// Sort rows by name length
bodyAreaModel.sort((a, b) => a.name.length - b.name.length);
// Sort rows by a computed value
bodyAreaModel.sort((a, b) => {
const scoreA = a.wins * 3 + a.draws;
const scoreB = b.wins * 3 + b.draws;
return scoreB - scoreA; // Descending order
});
// Implementation example
sort(compareFn?: (a: any, b: any) => number): void {
if (!compareFn) return;
// Apply the custom sort function
this.rows.sort(compareFn);
}
AreaModelIf
Description
The AreaModelIf interface represents a model for a specific area of a table (header, body, or footer). It provides methods for accessing and manipulating data within that area.
In the GuiExpert Table library, a table is divided into three main areas:
Each of these areas can be further divided into three sections:
The AreaModelIf interface is a core component of the table's architecture. While simple tables might use basic data structures like arrays of arrays or arrays of objects, the GuiExpert Table library uses a more sophisticated model approach. An AreaModelIf implementation provides information about:
This model-based approach provides maximum flexibility for creating complex, interactive tables.
Example
Example
Example
See