JavaScript Data GridCore
- Description
- How to call a method
- Members
- Methods
- addHook
- addHookOnce
- alter
- batch
- batchExecution
- batchRender
- clear
- clearUndo
- colToProp
- countColHeaders
- countCols
- countEmptyCols
- countEmptyRows
- countRenderedCols
- countRenderedRows
- countRowHeaders
- countRows
- countSourceCols
- countSourceRows
- countVisibleCols
- countVisibleRows
- deselectCell
- destroy
- destroyEditor
- emptySelectedCells
- getActiveEditor
- getCell
- getCellEditor
- getCellMeta
- getCellMetaAtRow
- getCellRenderer
- getCellsMeta
- getCellValidator
- getColHeader
- getColumnMeta
- getColWidth
- getCoords
- getCopyableData
- getCopyableText
- getData
- getDataAtCell
- getDataAtCol
- getDataAtProp
- getDataAtRow
- getDataAtRowProp
- getDataType
- getDirectionFactor
- getFirstFullyVisibleColumn
- getFirstFullyVisibleRow
- getFirstPartiallyVisibleColumn
- getFirstPartiallyVisibleRow
- getFirstRenderedVisibleColumn
- getFirstRenderedVisibleRow
- getFocusManager
- getInstance
- getLastFullyVisibleColumn
- getLastFullyVisibleRow
- getLastPartiallyVisibleColumn
- getLastPartiallyVisibleRow
- getLastRenderedVisibleColumn
- getLastRenderedVisibleRow
- getPlugin
- getRowHeader
- getRowHeight
- getSchema
- getSelected
- getSelectedLast
- getSelectedRange
- getSelectedRangeLast
- getSettings
- getShortcutManager
- getSourceData
- getSourceDataArray
- getSourceDataAtCell
- getSourceDataAtCol
- getSourceDataAtRow
- getTranslatedPhrase
- getValue
- hasColHeaders
- hasHook
- hasRowHeaders
- isColumnModificationAllowed
- isEmptyCol
- isEmptyRow
- isExecutionSuspended
- isListening
- isLtr
- isRedoAvailable
- isRenderSuspended
- isRtl
- isUndoAvailable
- listen
- loadData
- populateFromArray
- propToCol
- redo
- refreshDimensions
- removeCellMeta
- removeHook
- render
- resumeExecution
- resumeRender
- runHooks
- scrollToFocusedCell
- scrollViewportTo
- selectAll
- selectCell
- selectCells
- selectColumns
- selectRows
- setCellMeta
- setCellMetaObject
- setDataAtCell
- setDataAtRowProp
- setSourceDataAtCell
- spliceCellsMeta
- spliceCol
- spliceRow
- suspendExecution
- suspendRender
- toHTML
- toPhysicalColumn
- toPhysicalRow
- toTableElement
- toVisualColumn
- toVisualRow
- undo
- unlisten
- updateData
- updateSettings
- validateCell
- validateCells
- validateColumns
- validateRows
Description
The Handsontable
class (known as the Core
) lets you modify the grid's behavior by using Handsontable's public API methods.
How to call a method
// create a Handsontable instance
const hot = new Handsontable(document.getElementById('example'), options);
// call a method
hot.setDataAtCell(0, 0, 'new value');
Members
columnIndexMapper
Source codecore.columnIndexMapper : IndexMapper
Instance of index mapper which is responsible for managing the column indexes.
isDestroyed
Source codecore.isDestroyed : boolean
A boolean to tell if the Handsontable has been fully destroyed. This is set to true
after afterDestroy
hook is called.
rowIndexMapper
Source codecore.rowIndexMapper : IndexMapper
Instance of index mapper which is responsible for managing the row indexes.
Methods
addHook
Source codecore.addHook(key, callback, [orderIndex])
Adds listener to the specified hook name (only for this Handsontable instance).
See: Hooks#add
Example
hot.addHook('beforeInit', myCallback);
Param | Type | Description |
---|---|---|
key | string | Hook name (see Hooks). |
callback | function Array | Function or array of functions. |
[orderIndex] | number | optional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes. |
addHookOnce
Source codecore.addHookOnce(key, callback, [orderIndex])
Adds listener to specified hook name (only for this Handsontable instance). After the listener is triggered, it will be automatically removed.
See: Hooks#once
Example
hot.addHookOnce('beforeInit', myCallback);
Param | Type | Description |
---|---|---|
key | string | Hook name (see Hooks). |
callback | function Array | Function or array of functions. |
[orderIndex] | number | optional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes. |
alter
Source codecore.alter(action, [index], [amount], [source], [keepEmptyRows])
The alter()
method lets you alter the grid's structure
by adding or removing rows and columns at specified positions.
TIP
If you use an array of objects in your data
, the column-related actions won't work.
// above row 10 (by visual index), insert 1 new row
hot.alter('insert_row_above', 10);
Action | With index | Without index |
---|---|---|
'insert_row_above' | Inserts rows above the index row. | Inserts rows above the first row. |
'insert_row_below' | Inserts rows below the index row. | Inserts rows below the last row. |
'remove_row' | Removes rows, starting from the index row. | Removes rows, starting from the last row. |
'insert_col_start' | Inserts columns before the index column. | Inserts columns before the first column. |
'insert_col_end' | Inserts columns after the index column. | Inserts columns after the last column. |
'remove_col' | Removes columns, starting from the index column. | Removes columns, starting from the last column. |
Additional information about 'insert_col_start'
and 'insert_col_end'
:
- Their behavior depends on your
layoutDirection
. - If the provided
index
is higher than the actual number of columns, Handsontable doesn't generate the columns missing in between. Instead, the new columns are inserted next to the last column.
Example
// above row 10 (by visual index), insert 1 new row
hot.alter('insert_row_above', 10);
// below row 10 (by visual index), insert 3 new rows
hot.alter('insert_row_below', 10, 3);
// in the LTR layout direction: to the left of column 10 (by visual index), insert 3 new columns
// in the RTL layout direction: to the right of column 10 (by visual index), insert 3 new columns
hot.alter('insert_col_start', 10, 3);
// in the LTR layout direction: to the right of column 10 (by visual index), insert 1 new column
// in the RTL layout direction: to the left of column 10 (by visual index), insert 1 new column
hot.alter('insert_col_end', 10);
// remove 2 rows, starting from row 10 (by visual index)
hot.alter('remove_row', 10, 2);
// remove 3 rows, starting from row 1 (by visual index)
// remove 2 rows, starting from row 5 (by visual index)
hot.alter('remove_row', [[1, 3], [5, 2]]);
Param | Type | Description |
---|---|---|
action | string | Available operations:
|
[index] | number Array<number> | optional A visual index of the row/column before or after which the new row/column will be inserted or removed. Can also be an array of arrays, in format [[index, amount],...] . |
[amount] | number | optional The amount of rows or columns to be inserted or removed (default: 1 ). |
[source] | string | optional Source indicator. |
[keepEmptyRows] | boolean | optional If set to true : prevents removing empty rows. |
batch
Source codecore.batch(wrappedOperations) ⇒ *
It batches the rendering process and index recalculations. The method aggregates multi-line API calls into a callback and postpones the table rendering process as well aggregates the table logic changes such as index changes into one call after which the cache is updated. After the execution of the operations, the table is rendered, and the cache is updated once. As a result, it improves the performance of wrapped operations.
Since: 8.3.0
Example
hot.batch(() => {
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 10, 40);
hot.setDataAtCell(1, 1, 'x');
hot.setDataAtCell(2, 2, 'c');
hot.setDataAtCell(3, 3, 'v');
hot.setDataAtCell(4, 4, 'b');
hot.setDataAtCell(5, 5, 'n');
hot.selectCell(0, 0);
const filters = hot.getPlugin('filters');
filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
// The table will be re-rendered and cache will be recalculated once after executing the callback
});
Param | Type | Description |
---|---|---|
wrappedOperations | function | Batched operations wrapped in a function. |
Returns: *
- Returns result from the wrappedOperations callback.
batchExecution
Source codecore.batchExecution(wrappedOperations, [forceFlushChanges]) ⇒ *
The method aggregates multi-line API calls into a callback and postpones the table execution process. After the execution of the operations, the internal table cache is recalculated once. As a result, it improves the performance of wrapped operations. Without batching, a similar case could trigger multiple table cache rebuilds.
Since: 8.3.0
Example
hot.batchExecution(() => {
const filters = hot.getPlugin('filters');
filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
// The table cache will be recalculated once after executing the callback
});
Param | Type | Default | Description |
---|---|---|---|
wrappedOperations | function | Batched operations wrapped in a function. | |
[forceFlushChanges] | boolean | false | optional If true , the table internal data cache is recalculated after the execution of the batched operations. For nested calls, it can be a desire to recalculate the table after each batch. |
Returns: *
- Returns result from the wrappedOperations callback.
batchRender
Source codecore.batchRender(wrappedOperations) ⇒ *
The method aggregates multi-line API calls into a callback and postpones the table rendering process. After the execution of the operations, the table is rendered once. As a result, it improves the performance of wrapped operations. Without batching, a similar case could trigger multiple table render calls.
Since: 8.3.0
Example
hot.batchRender(() => {
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 10, 40);
hot.setDataAtCell(1, 1, 'John');
hot.setDataAtCell(2, 2, 'Mark');
hot.setDataAtCell(3, 3, 'Ann');
hot.setDataAtCell(4, 4, 'Sophia');
hot.setDataAtCell(5, 5, 'Mia');
hot.selectCell(0, 0);
// The table will be rendered once after executing the callback
});
Param | Type | Description |
---|---|---|
wrappedOperations | function | Batched operations wrapped in a function. |
Returns: *
- Returns result from the wrappedOperations callback.
clear
Source codecore.clear()
Clears the data from the table (the table settings remain intact).
clearUndo
Source codecore.clearUndo() ⇒ boolean
colToProp
Source codecore.colToProp(column) ⇒ string | number
Returns the property name that corresponds with the given column index. If the data source is an array of arrays, it returns the columns index.
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
Returns: string
| number
- Column property or physical column index.
countColHeaders
Source codecore.countColHeaders() ⇒ number
Returns the number of rendered column headers.
Since: 14.0.0
Returns: number
- Number of column headers.
countCols
Source codecore.countCols() ⇒ number
Returns the total number of visible columns in the table.
Returns: number
- Total number of columns.
countEmptyCols
Source codecore.countEmptyCols([ending]) ⇒ number
Returns the number of empty columns. If the optional ending parameter is true
, returns the number of empty
columns at right hand edge of the table.
Param | Type | Default | Description |
---|---|---|---|
[ending] | boolean | false | optional If true , will only count empty columns at the end of the data source row. |
Returns: number
- Count empty cols.
countEmptyRows
Source codecore.countEmptyRows([ending]) ⇒ number
Returns the number of empty rows. If the optional ending parameter is true
, returns the
number of empty rows at the bottom of the table.
Param | Type | Default | Description |
---|---|---|---|
[ending] | boolean | false | optional If true , will only count empty rows at the end of the data source. |
Returns: number
- Count empty rows.
countRenderedCols
Source codecore.countRenderedCols() ⇒ number
Returns the number of rendered rows including columns that are partially or fully rendered outside the table viewport.
Returns: number
- Returns -1 if table is not visible.
countRenderedRows
Source codecore.countRenderedRows() ⇒ number
Returns the number of rendered rows including rows that are partially or fully rendered outside the table viewport.
Returns: number
- Returns -1 if table is not visible.
countRowHeaders
Source codecore.countRowHeaders() ⇒ number
Returns the number of rendered row headers.
Since: 14.0.0
Returns: number
- Number of row headers.
countRows
Source codecore.countRows() ⇒ number
Returns the total number of visual rows in the table.
Returns: number
- Total number of rows.
countSourceCols
Source codecore.countSourceCols() ⇒ number
Returns the total number of columns in the data source.
Returns: number
- Total number of columns.
countSourceRows
Source codecore.countSourceRows() ⇒ number
Returns the total number of rows in the data source.
Returns: number
- Total number of rows.
countVisibleCols
Source codecore.countVisibleCols() ⇒ number
Returns the number of rendered columns that are only visible in the table viewport. The columns that are partially visible are not counted.
Returns: number
- Number of visible columns or -1.
countVisibleRows
Source codecore.countVisibleRows() ⇒ number
Returns the number of rendered rows that are only visible in the table viewport. The rows that are partially visible are not counted.
Returns: number
- Number of visible rows or -1.
deselectCell
Source codecore.deselectCell()
Deselects the current cell selection on the table.
destroy
Source codecore.destroy()
Removes the table from the DOM and destroys the instance of the Handsontable.
Emits: Hooks#event:afterDestroy
destroyEditor
Source codecore.destroyEditor([revertOriginal], [prepareEditorIfNeeded])
Destroys the current editor, render the table and prepares the editor of the newly selected cell.
Param | Type | Default | Description |
---|---|---|---|
[revertOriginal] | boolean | false | optional If true , the previous value will be restored. Otherwise, the edited value will be saved. |
[prepareEditorIfNeeded] | boolean | true | optional If true the editor under the selected cell will be prepared to open. |
emptySelectedCells
Source codecore.emptySelectedCells([source])
Erases content from cells that have been selected in the table.
Since: 0.36.0
Param | Type | Description |
---|---|---|
[source] | string | optional String that identifies how this change will be described in the changes array (useful in afterChange or beforeChange callback). Set to 'edit' if left empty. |
getActiveEditor
Source codecore.getActiveEditor() ⇒ BaseEditor
Returns the active editor class instance.
Returns: BaseEditor
- The active editor instance.
getCell
Source codecore.getCell(row, column, [topmost]) ⇒ HTMLTableCellElement | null
Returns a TD element for the given row
and column
arguments, if it is rendered on screen.
Returns null
if the TD is not rendered on screen (probably because that part of the table is not visible).
Param | Type | Default | Description |
---|---|---|---|
row | number | Visual row index. | |
column | number | Visual column index. | |
[topmost] | boolean | false | optional If set to true , it returns the TD element from the topmost overlay. For example, if the wanted cell is in the range of fixed rows, it will return a TD element from the top overlay. |
Returns: HTMLTableCellElement
| null
- The cell's TD element.
getCellEditor
Source codecore.getCellEditor(rowOrMeta, column) ⇒ function | boolean
Returns the cell editor class by the provided row
and column
arguments.
Example
// Get cell editor class using `row` and `column` coordinates.
hot.getCellEditor(1, 1);
// Get cell editor class using cell meta object.
hot.getCellEditor(hot.getCellMeta(1, 1));
Param | Type | Description |
---|---|---|
rowOrMeta | number | Visual row index or cell meta object (see Core#getCellMeta). |
column | number | Visual column index. |
Returns: function
| boolean
- Returns the editor class or false
is cell editor is disabled.
getCellMeta
Source codecore.getCellMeta(row, column) ⇒ object
Returns the cell properties object for the given row
and column
coordinates.
Emits: Hooks#event:beforeGetCellMeta
, Hooks#event:afterGetCellMeta
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
Returns: object
- The cell properties object.
getCellMetaAtRow
Source codecore.getCellMetaAtRow(row) ⇒ Array
Returns an array of cell meta objects for specified physical row index.
Param | Type | Description |
---|---|---|
row | number | Physical row index. |
getCellRenderer
Source codecore.getCellRenderer(rowOrMeta, column) ⇒ function
Returns the cell renderer function by given row
and column
arguments.
Example
// Get cell renderer using `row` and `column` coordinates.
hot.getCellRenderer(1, 1);
// Get cell renderer using cell meta object.
hot.getCellRenderer(hot.getCellMeta(1, 1));
Param | Type | Description |
---|---|---|
rowOrMeta | number object | Visual row index or cell meta object (see Core#getCellMeta). |
column | number | Visual column index. |
Returns: function
- Returns the renderer function.
getCellsMeta
Source codecore.getCellsMeta() ⇒ Array
Get all the cells meta settings at least once generated in the table (in order of cell initialization).
Returns: Array
- Returns an array of ColumnSettings object instances.
getCellValidator
Source codecore.getCellValidator(rowOrMeta, column) ⇒ function | RegExp | undefined
Returns the cell validator by row
and column
.
Example
// Get cell validator using `row` and `column` coordinates.
hot.getCellValidator(1, 1);
// Get cell validator using cell meta object.
hot.getCellValidator(hot.getCellMeta(1, 1));
Param | Type | Description |
---|---|---|
rowOrMeta | number object | Visual row index or cell meta object (see Core#getCellMeta). |
column | number | Visual column index. |
Returns: function
| RegExp
| undefined
- The validator function.
getColHeader
Source codecore.getColHeader([column], [headerLevel]) ⇒ Array | string | number
Gets the values of column headers (if column headers are enabled).
To get an array with the values of all
bottom-most column headers,
call getColHeader()
with no arguments.
To get the value of the bottom-most header of a specific column, use the column
parameter.
To get the value of a specific-level header
of a specific column, use the column
and headerLevel
parameters.
Read more:
// get the contents of all bottom-most column headers
hot.getColHeader();
// get the contents of the bottom-most header of a specific column
hot.getColHeader(5);
// get the contents of a specific column header at a specific level
hot.getColHeader(5, -2);
Emits: Hooks#event:modifyColHeader
, Hooks#event:modifyColumnHeaderValue
Param | Type | Default | Description |
---|---|---|---|
[column] | number | optional A visual column index. | |
[headerLevel] | number | -1 | optional (Since 12.3.0) Header level index. Accepts positive (0 to n) and negative (-1 to -n) values. For positive values, 0 points to the topmost header. For negative values, -1 points to the bottom-most header (the header closest to the cells). |
Returns: Array
| string
| number
- Column header values.
getColumnMeta
Source codecore.getColumnMeta(column) ⇒ object
Returns the meta information for the provided column.
Since: 14.5.0
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
getColWidth
Source codecore.getColWidth(column) ⇒ number
Returns the width of the requested column.
Emits: Hooks#event:modifyColWidth
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
Returns: number
- Column width.
getCoords
Source codecore.getCoords(element) ⇒ CellCoords | null
Returns the coordinates of the cell, provided as a HTML table cell element.
Example
hot.getCoords(hot.getCell(1, 1));
// it returns CellCoords object instance with props row: 1 and col: 1.
Param | Type | Description |
---|---|---|
element | HTMLTableCellElement | The HTML Element representing the cell. |
Returns: CellCoords
| null
- Visual coordinates object.
getCopyableData
Source codecore.getCopyableData(row, column) ⇒ string
Returns the data's copyable value at specified row
and column
index.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
getCopyableText
Source codecore.getCopyableText(startRow, startCol, endRow, endCol) ⇒ string
Returns a string value of the selected range. Each column is separated by tab, each row is separated by a new line character.
Param | Type | Description |
---|---|---|
startRow | number | From visual row index. |
startCol | number | From visual column index. |
endRow | number | To visual row index. |
endCol | number | To visual column index. |
getData
Source codecore.getData([row], [column], [row2], [column2]) ⇒ Array<Array>
Returns the current data object (the same one that was passed by data
configuration option or loadData
method,
unless some modifications have been applied (i.e. Sequence of rows/columns was changed, some row/column was skipped).
If that's the case - use the Core#getSourceData method.).
Optionally you can provide cell range by defining row
, column
, row2
, column2
to get only a fragment of table data.
Example
// Get all data (in order how it is rendered in the table).
hot.getData();
// Get data fragment (from top-left 0, 0 to bottom-right 3, 3).
hot.getData(3, 3);
// Get data fragment (from top-left 2, 1 to bottom-right 3, 3).
hot.getData(2, 1, 3, 3);
Param | Type | Description |
---|---|---|
[row] | number | optional From visual row index. |
[column] | number | optional From visual column index. |
[row2] | number | optional To visual row index. |
[column2] | number | optional To visual column index. |
Returns: Array<Array>
- Array with the data.
getDataAtCell
Source codecore.getDataAtCell(row, column) ⇒ *
Returns the cell value at row
, column
.
Note: If data is reordered, sorted or trimmed, the currently visible order will be used.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
Returns: *
- Data at cell.
getDataAtCol
Source codecore.getDataAtCol(column) ⇒ Array
Returns array of column values from the data source.
Note: If columns were reordered or sorted, the currently visible order will be used.
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
Returns: Array
- Array of cell values.
getDataAtProp
Source codecore.getDataAtProp(prop) ⇒ Array
Given the object property name (e.g. 'first.name'
or '0'
), returns an array of column's values from the table data.
You can also provide a column index as the first argument.
Param | Type | Description |
---|---|---|
prop | string number | Property name or physical column index. |
Returns: Array
- Array of cell values.
getDataAtRow
Source codecore.getDataAtRow(row) ⇒ Array
Returns a single row of the data.
Note: If rows were reordered, sorted or trimmed, the currently visible order will be used.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
Returns: Array
- Array of row's cell data.
getDataAtRowProp
Source codecore.getDataAtRowProp(row, prop) ⇒ *
Returns value at visual row
and prop
indexes.
Note: If data is reordered, sorted or trimmed, the currently visible order will be used.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
prop | string | Property name. |
Returns: *
- Cell value.
getDataType
Source codecore.getDataType(rowFrom, columnFrom, rowTo, columnTo) ⇒ string
Returns a data type defined in the Handsontable settings under the type
key (Options#type).
If there are cells with different types in the selected range, it returns 'mixed'
.
Note: If data is reordered, sorted or trimmed, the currently visible order will be used.
Param | Type | Description |
---|---|---|
rowFrom | number | From visual row index. |
columnFrom | number | From visual column index. |
rowTo | number | To visual row index. |
columnTo | number | To visual column index. |
Returns: string
- Cell type (e.q: 'mixed'
, 'text'
, 'numeric'
, 'autocomplete'
).
getDirectionFactor
Source codecore.getDirectionFactor() ⇒ number
Returns 1 for LTR; -1 for RTL. Useful for calculations.
Since: 12.0.0
Returns: number
- Returns 1 for LTR; -1 for RTL.
getFirstFullyVisibleColumn
Source codecore.getFirstFullyVisibleColumn() ⇒ number | null
Returns the first fully visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getFirstFullyVisibleRow
Source codecore.getFirstFullyVisibleRow() ⇒ number | null
Returns the first fully visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getFirstPartiallyVisibleColumn
Source codecore.getFirstPartiallyVisibleColumn() ⇒ number | null
Returns the first partially visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getFirstPartiallyVisibleRow
Source codecore.getFirstPartiallyVisibleRow() ⇒ number | null
Returns the first partially visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getFirstRenderedVisibleColumn
Source codecore.getFirstRenderedVisibleColumn() ⇒ number | null
Returns the first rendered column in the DOM (usually, it is not visible in the table's viewport).
Since: 14.6.0
getFirstRenderedVisibleRow
Source codecore.getFirstRenderedVisibleRow() ⇒ number | null
Returns the first rendered row in the DOM (usually, it is not visible in the table's viewport).
Since: 14.6.0
getFocusManager
Source codecore.getFocusManager() ⇒ FocusManager
Return the Focus Manager responsible for managing the browser's focus in the table.
Since: 14.0.0
getInstance
Source codecore.getInstance() ⇒ Handsontable
Returns the Handsontable instance.
Returns: Handsontable
- The Handsontable instance.
getLastFullyVisibleColumn
Source codecore.getLastFullyVisibleColumn() ⇒ number | null
Returns the last fully visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getLastFullyVisibleRow
Source codecore.getLastFullyVisibleRow() ⇒ number | null
Returns the last fully visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getLastPartiallyVisibleColumn
Source codecore.getLastPartiallyVisibleColumn() ⇒ number | null
Returns the last partially visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getLastPartiallyVisibleRow
Source codecore.getLastPartiallyVisibleRow() ⇒ number | null
Returns the last partially visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.
Since: 14.6.0
getLastRenderedVisibleColumn
Source codecore.getLastRenderedVisibleColumn() ⇒ number | null
Returns the last rendered column in the DOM (usually, it is not visible in the table's viewport).
Since: 14.6.0
getLastRenderedVisibleRow
Source codecore.getLastRenderedVisibleRow() ⇒ number | null
Returns the last rendered row in the DOM (usually, it is not visible in the table's viewport).
Since: 14.6.0
getPlugin
Source codecore.getPlugin(pluginName) ⇒ BasePlugin | undefined
Returns plugin instance by provided its name.
Param | Type | Description |
---|---|---|
pluginName | string | The plugin name. |
Returns: BasePlugin
| undefined
- The plugin instance or undefined if there is no plugin.
getRowHeader
Source codecore.getRowHeader([row]) ⇒ Array | string | number
Returns an array of row headers' values (if they are enabled). If param row
was given, it returns the header of the given row as a string.
Emits: Hooks#event:modifyRowHeader
Param | Type | Description |
---|---|---|
[row] | number | optional Visual row index. |
Returns: Array
| string
| number
- Array of header values / single header value.
getRowHeight
Source codecore.getRowHeight(row) ⇒ number | undefined
Returns a row's height, as recognized by Handsontable.
Depending on your configuration, the method returns (in order of priority):
- The row height set by the
ManualRowResize
plugin (if the plugin is enabled). - The row height set by the
rowHeights
configuration option (if the option is set). - The row height as measured in the DOM by the
AutoRowSize
plugin (if the plugin is enabled). undefined
, if neitherManualRowResize
, norrowHeights
, norAutoRowSize
is used.
The height returned includes 1 px of the row's bottom border.
Mind that this method is different from the
getRowHeight()
method
of the AutoRowSize
plugin.
Emits: Hooks#event:modifyRowHeight
Param | Type | Description |
---|---|---|
row | number | A visual row index. |
Returns: number
| undefined
- The height of the specified row, in pixels.
getSchema
Source codecore.getSchema() ⇒ object
Returns schema provided by constructor settings. If it doesn't exist then it returns the schema based on the data structure in the first row.
Returns: object
- Schema object.
getSelected
Source codecore.getSelected() ⇒ Array<Array> | undefined
Returns indexes of the currently selected cells as an array of arrays [[startRow, startCol, endRow, endCol],...]
.
Start row and start column are the coordinates of the active cell (where the selection was started).
The version 0.36.0 adds a non-consecutive selection feature. Since this version, the method returns an array of arrays.
Additionally to collect the coordinates of the currently selected area (as it was previously done by the method)
you need to use getSelectedLast
method.
Returns: Array<Array>
| undefined
- An array of arrays of the selection's coordinates.
getSelectedLast
Source codecore.getSelectedLast() ⇒ Array | undefined
Returns the last coordinates applied to the table as a an array [startRow, startCol, endRow, endCol]
.
Since: 0.36.0
Returns: Array
| undefined
- An array of the selection's coordinates.
getSelectedRange
Source codecore.getSelectedRange() ⇒ Array<CellRange> | undefined
Returns the current selection as an array of CellRange objects.
The version 0.36.0 adds a non-consecutive selection feature. Since this version, the method returns an array of arrays.
Additionally to collect the coordinates of the currently selected area (as it was previously done by the method)
you need to use getSelectedRangeLast
method.
Returns: Array<[CellRange](/javascript-data-grid/api/cell-range/)>
| undefined
- Selected range object or undefined if there is no selection.
getSelectedRangeLast
Source codecore.getSelectedRangeLast() ⇒ CellRange | undefined
Returns the last coordinates applied to the table as a CellRange object.
Since: 0.36.0
Returns: CellRange
| undefined
- Selected range object or undefined` if there is no selection.
getSettings
Source codecore.getSettings() ⇒ TableMeta
Returns the object settings.
Returns: TableMeta
- Object containing the current table settings.
getShortcutManager
Source codecore.getShortcutManager() ⇒ ShortcutManager
Returns instance of a manager responsible for handling shortcuts stored in some contexts. It run actions after pressing key combination in active Handsontable instance.
Since: 12.0.0
Returns: ShortcutManager
- Instance of ShortcutManager
getSourceData
Source codecore.getSourceData([row], [column], [row2], [column2]) ⇒ Array<Array> | Array<object>
Returns a clone of the source data object.
Optionally you can provide a cell range by using the row
, column
, row2
, column2
arguments, to get only a
fragment of the table data.
Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.
Note: This method may return incorrect values for cells that contain
formulas. This is because getSourceData()
operates on source data (physical indexes),
whereas formulas operate on visual data (visual indexes).
Param | Type | Description |
---|---|---|
[row] | number | optional From physical row index. |
[column] | number | optional From physical column index (or visual index, if data type is an array of objects). |
[row2] | number | optional To physical row index. |
[column2] | number | optional To physical column index (or visual index, if data type is an array of objects). |
Returns: Array<Array>
| Array<object>
- The table data.
getSourceDataArray
Source codecore.getSourceDataArray([row], [column], [row2], [column2]) ⇒ Array
Returns the source data object as an arrays of arrays format even when source data was provided in another format.
Optionally you can provide a cell range by using the row
, column
, row2
, column2
arguments, to get only a
fragment of the table data.
Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.
Param | Type | Description |
---|---|---|
[row] | number | optional From physical row index. |
[column] | number | optional From physical column index (or visual index, if data type is an array of objects). |
[row2] | number | optional To physical row index. |
[column2] | number | optional To physical column index (or visual index, if data type is an array of objects). |
Returns: Array
- An array of arrays.
getSourceDataAtCell
Source codecore.getSourceDataAtCell(row, column) ⇒ *
Returns a single value from the data source.
Param | Type | Description |
---|---|---|
row | number | Physical row index. |
column | number | Visual column index. |
Returns: *
- Cell data.
getSourceDataAtCol
Source codecore.getSourceDataAtCol(column) ⇒ Array
Returns an array of column values from the data source.
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
Returns: Array
- Array of the column's cell values.
getSourceDataAtRow
Source codecore.getSourceDataAtRow(row) ⇒ Array | object
Returns a single row of the data (array or object, depending on what data format you use).
Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.
Param | Type | Description |
---|---|---|
row | number | Physical row index. |
Returns: Array
| object
- Single row of data.
getTranslatedPhrase
Source codecore.getTranslatedPhrase(dictionaryKey, extraArguments) ⇒ string
Get language phrase for specified dictionary key.
Since: 0.35.0
Param | Type | Description |
---|---|---|
dictionaryKey | string | Constant which is dictionary key. |
extraArguments | * | Arguments which will be handled by formatters. |
getValue
Source codecore.getValue() ⇒ *
Gets the value of the currently focused cell.
For column headers and row headers, returns null
.
Returns: *
- The value of the focused cell.
hasColHeaders
Source codecore.hasColHeaders() ⇒ boolean
Returns information about if this table is configured to display column headers.
Returns: boolean
- true
if the instance has the column headers enabled, false
otherwise.
hasHook
Source codecore.hasHook(key) ⇒ boolean
Check if for a specified hook name there are added listeners (only for this Handsontable instance). All available hooks you will find Hooks.
See: Hooks#has
Example
const hasBeforeInitListeners = hot.hasHook('beforeInit');
Param | Type | Description |
---|---|---|
key | string | Hook name. |
hasRowHeaders
Source codecore.hasRowHeaders() ⇒ boolean
Returns information about if this table is configured to display row headers.
Returns: boolean
- true
if the instance has the row headers enabled, false
otherwise.
isColumnModificationAllowed
Source codecore.isColumnModificationAllowed() ⇒ boolean
Checks if your data format and configuration options allow for changing the number of columns.
Returns false
when your data is an array of objects,
or when you use the columns
option.
Otherwise, returns true
.
isEmptyCol
Source codecore.isEmptyCol(column) ⇒ boolean
Check if all cells in the the column declared by the column
argument are empty.
Param | Type | Description |
---|---|---|
column | number | Column index. |
Returns: boolean
- true
if the column at the given col
is empty, false
otherwise.
isEmptyRow
Source codecore.isEmptyRow(row) ⇒ boolean
Check if all cells in the row declared by the row
argument are empty.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
Returns: boolean
- true
if the row at the given row
is empty, false
otherwise.
isExecutionSuspended
Source codecore.isExecutionSuspended() ⇒ boolean
Checks if the table indexes recalculation process was suspended. See explanation in Core#suspendExecution.
Since: 8.3.0
isListening
Source codecore.isListening() ⇒ boolean
Returns true
if the current Handsontable instance is listening to keyboard input on document body.
Returns: boolean
- true
if the instance is listening, false
otherwise.
isLtr
Source codecore.isLtr() ⇒ boolean
Checks if the grid is rendered using the left-to-right layout direction.
Since: 12.0.0
Returns: boolean
- True if LTR.
isRedoAvailable
Source codecore.isRedoAvailable() ⇒ boolean
isRenderSuspended
Source codecore.isRenderSuspended() ⇒ boolean
Checks if the table rendering process was suspended. See explanation in Core#suspendRender.
Since: 8.3.0
isRtl
Source codecore.isRtl() ⇒ boolean
Checks if the grid is rendered using the right-to-left layout direction.
Since: 12.0.0
Returns: boolean
- True if RTL.
isUndoAvailable
Source codecore.isUndoAvailable() ⇒ boolean
listen
Source codecore.listen()
Listen to the keyboard input on document body. This allows Handsontable to capture keyboard events and respond in the right way.
Emits: Hooks#event:afterListen
loadData
Source codecore.loadData(data, [source])
The loadData()
method replaces Handsontable's data
with a new dataset.
Additionally, the loadData()
method:
- Resets cells' states (e.g. cells' formatting and cells'
readOnly
states) - Resets rows' states (e.g. row order)
- Resets columns' states (e.g. column order)
To replace Handsontable's data
without resetting states, use the updateData()
method.
Read more:
Emits: Hooks#event:beforeLoadData
, Hooks#event:afterLoadData
, Hooks#event:afterChange
Param | Type | Description |
---|---|---|
data | Array | An array of arrays, or an array of objects, that contains Handsontable's data |
[source] | string | optional The source of the loadData() call |
populateFromArray
Source codecore.populateFromArray(row, column, input, [endRow], [endCol], [source], [method]) ⇒ object | undefined
Populates cells at position with 2D input array (e.g. [[1, 2], [3, 4]]
). Use endRow
, endCol
when you
want to cut input when a certain row is reached.
The populateFromArray()
method can't change readOnly
cells.
Optional method
argument has the same effect as pasteMode option (see Options#pasteMode).
Param | Type | Default | Description |
---|---|---|---|
row | number | Start visual row index. | |
column | number | Start visual column index. | |
input | Array | 2d array. | |
[endRow] | number | optional End visual row index (use when you want to cut input when certain row is reached). | |
[endCol] | number | optional End visual column index (use when you want to cut input when certain column is reached). | |
[source] | string | "populateFromArray" | optional Used to identify this call in the resulting events (beforeChange, afterChange). |
[method] | string | "overwrite" | optional Populate method, possible values: 'shift_down' , 'shift_right' , 'overwrite' . |
Returns: object
| undefined
- Ending td in pasted area (only if any cell was changed).
propToCol
Source codecore.propToCol(prop) ⇒ number
Returns column index that corresponds with the given property.
Param | Type | Description |
---|---|---|
prop | string number | Property name or physical column index. |
Returns: number
- Visual column index.
redo
Source codecore.redo() ⇒ boolean
refreshDimensions
Source codecore.refreshDimensions()
Updates dimensions of the table. The method compares previous dimensions with the current ones and updates accordingly.
Emits: Hooks#event:beforeRefreshDimensions
, Hooks#event:afterRefreshDimensions
removeCellMeta
Source codecore.removeCellMeta(row, column, key)
Remove a property defined by the key
argument from the cell meta object for the provided row
and column
coordinates.
Emits: Hooks#event:beforeRemoveCellMeta
, Hooks#event:afterRemoveCellMeta
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
key | string | Property name. |
removeHook
Source codecore.removeHook(key, callback)
Removes the hook listener previously registered with Core#addHook.
See: Hooks#remove
Example
hot.removeHook('beforeInit', myCallback);
Param | Type | Description |
---|---|---|
key | string | Hook name. |
callback | function | Reference to the function which has been registered using Core#addHook. |
render
Source codecore.render()
Rerender the table. Calling this method starts the process of recalculating, redrawing and applying the changes to the DOM. While rendering the table all cell renderers are recalled.
Calling this method manually is not recommended. Handsontable tries to render itself by choosing the most optimal moments in its lifecycle.
resumeExecution
Source codecore.resumeExecution([forceFlushChanges])
Resumes the execution process. In combination with the Core#suspendExecution method it allows aggregating the table logic changes after which the cache is updated. Resuming the state automatically invokes the table cache updating process.
The method is intended to be used by advanced users. Suspending the execution process could cause visual glitches caused by not updated the internal table cache.
Since: 8.3.0
Example
hot.suspendExecution();
const filters = hot.getPlugin('filters');
filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
hot.resumeExecution(); // It updates the cache internally
Param | Type | Default | Description |
---|---|---|---|
[forceFlushChanges] | boolean | false | optional If true , the table internal data cache is recalculated after the execution of the batched operations. For nested Core#batchExecution calls, it can be desire to recalculate the table after each batch. |
resumeRender
Source codecore.resumeRender()
Resumes the rendering process. In combination with the Core#suspendRender method it allows aggregating the table render cycles triggered by API calls or UI actions (or both) and calls the "render" once in the end. When the table is in the suspend state, most operations will have no visual effect until the rendering state is resumed. Resuming the state automatically invokes the table rendering.
The method is intended to be used by advanced users. Suspending the rendering process could cause visual glitches when wrongly implemented.
Every suspendRender()
call needs to correspond with one resumeRender()
call.
For example, if you call suspendRender()
5 times, you need to call resumeRender()
5 times as well.
Since: 8.3.0
Example
hot.suspendRender();
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 10, 40);
hot.setDataAtCell(1, 1, 'John');
hot.setDataAtCell(2, 2, 'Mark');
hot.setDataAtCell(3, 3, 'Ann');
hot.setDataAtCell(4, 4, 'Sophia');
hot.setDataAtCell(5, 5, 'Mia');
hot.selectCell(0, 0);
hot.resumeRender(); // It re-renders the table internally
runHooks
Source codecore.runHooks(key, [p1], [p2], [p3], [p4], [p5], [p6]) ⇒ *
Run the callbacks for the hook provided in the key
argument using the parameters given in the other arguments.
See: Hooks#run
Example
// Run built-in hook
hot.runHooks('beforeInit');
// Run custom hook
hot.runHooks('customAction', 10, 'foo');
Param | Type | Description |
---|---|---|
key | string | Hook name. |
[p1] | * | optional Argument passed to the callback. |
[p2] | * | optional Argument passed to the callback. |
[p3] | * | optional Argument passed to the callback. |
[p4] | * | optional Argument passed to the callback. |
[p5] | * | optional Argument passed to the callback. |
[p6] | * | optional Argument passed to the callback. |
scrollToFocusedCell
Source codecore.scrollToFocusedCell(callback)
Scrolls the viewport to coordinates specified by the currently focused cell.
Emits: Hooks#event:afterScroll
Since: 14.0.0
Param | Type | Description |
---|---|---|
callback | function | The callback function to call after the viewport is scrolled. |
scrollViewportTo
Source codecore.scrollViewportTo(options) ⇒ boolean
Scroll viewport to coordinates specified by the row
and/or col
object properties.
// scroll the viewport to the visual row index (leave the horizontal scroll untouched)
hot.scrollViewportTo({ row: 50 });
// scroll the viewport to the passed coordinates so that the cell at 50, 50 will be snapped to
// the bottom-end table's edge.
hot.scrollViewportTo({
row: 50,
col: 50,
verticalSnap: 'bottom',
horizontalSnap: 'end',
});
Param | Type | Default | Description |
---|---|---|---|
options | object | A dictionary containing the following parameters: | |
[options.row] | number | optional Specifies the number of visual rows along the Y axis to scroll the viewport. | |
[options.col] | number | optional Specifies the number of visual columns along the X axis to scroll the viewport. | |
[options.verticalSnap] | 'top' 'bottom' | optional Determines to which edge of the table the viewport will be scrolled based on the passed coordinates. This option is a string which must take one of the following values: - top : The viewport will be scrolled to a row in such a way that it will be positioned on the top of the viewport; - bottom : The viewport will be scrolled to a row in such a way that it will be positioned on the bottom of the viewport; - If the property is not defined the vertical auto-snapping is enabled. Depending on where the viewport is scrolled from, a row will be positioned at the top or bottom of the viewport. | |
[options.horizontalSnap] | 'start' 'end' | optional Determines to which edge of the table the viewport will be scrolled based on the passed coordinates. This option is a string which must take one of the following values: - start : The viewport will be scrolled to a column in such a way that it will be positioned on the start (left edge or right, if the layout direction is set to rtl ) of the viewport; - end : The viewport will be scrolled to a column in such a way that it will be positioned on the end (right edge or left, if the layout direction is set to rtl ) of the viewport; - If the property is not defined the horizontal auto-snapping is enabled. Depending on where the viewport is scrolled from, a column will be positioned at the start or end of the viewport. | |
[options.considerHiddenIndexes] | boolean | true | optional If true , we handle visual indexes, otherwise we handle only indexes which may be rendered when they are in the viewport (we don't consider hidden indexes as they aren't rendered). |
Returns: boolean
- true
if viewport was scrolled, false
otherwise.
selectAll
Source codecore.selectAll([includeRowHeaders], [includeColumnHeaders], [options])
Select all cells in the table excluding headers and corner elements.
The previous selection is overwritten.
// Select all cells in the table along with row headers, including all headers and the corner cell.
// Doesn't select column headers and corner elements.
hot.selectAll();
// Select all cells in the table, including row headers but excluding the corner cell and column headers.
hot.selectAll(true, false);
// Select all cells in the table, including all headers and the corner cell, but move the focus.
// highlight to position 2, 1
hot.selectAll(-2, -1, {
focusPosition: { row: 2, col: 1 }
});
// Select all cells in the table, without headers and corner elements.
hot.selectAll(false);
Since: 0.38.2
Param | Type | Default | Description |
---|---|---|---|
[includeRowHeaders] | boolean | false | optional true If the selection should include the row headers, false otherwise. |
[includeColumnHeaders] | boolean | false | optional true If the selection should include the column headers, false otherwise. |
[options] | object | optional Additional object with options. Since 14.0.0 | |
[options.focusPosition] | Object boolean | optional The argument allows changing the cell/header focus position. The value takes an object with a row and col properties from -N to N, where negative values point to the headers and positive values point to the cell range. If false , the focus position won't be changed. Example: js hot.selectAll(0, 0, { focusPosition: { row: 0, col: 1 }, disableHeadersHighlight: true }) | |
[options.disableHeadersHighlight] | boolean | optional If true , disables highlighting the headers even when the logical coordinates points on them. |
selectCell
Source codecore.selectCell(row, column, [endRow], [endColumn], [scrollToCell], [changeListener]) ⇒ boolean
Select a single cell, or a single range of adjacent cells.
To select a cell, pass its visual row and column indexes, for example: selectCell(2, 4)
.
To select a range, pass the visual indexes of the first and last cell in the range, for example: selectCell(2, 4, 3, 5)
.
If your columns have properties, you can pass those properties' values instead of column indexes, for example: selectCell(2, 'first_name')
.
By default, selectCell()
also:
- Scrolls the viewport to the newly-selected cells.
- Switches the keyboard focus to Handsontable (by calling Handsontable's
listen()
method).
Example
// select a single cell
hot.selectCell(2, 4);
// select a range of cells
hot.selectCell(2, 4, 3, 5);
// select a single cell, using a column property
hot.selectCell(2, 'first_name');
// select a range of cells, using column properties
hot.selectCell(2, 'first_name', 3, 'last_name');
// select a range of cells, without scrolling to them
hot.selectCell(2, 4, 3, 5, false);
// select a range of cells, without switching the keyboard focus to Handsontable
hot.selectCell(2, 4, 3, 5, null, false);
Param | Type | Default | Description |
---|---|---|---|
row | number | A visual row index. | |
column | number string | A visual column index (number ), or a column property's value (string ). | |
[endRow] | number | optional If selecting a range: the visual row index of the last cell in the range. | |
[endColumn] | number string | optional If selecting a range: the visual column index (or a column property's value) of the last cell in the range. | |
[scrollToCell] | boolean | true | optional true : scroll the viewport to the newly-selected cells. false : keep the previous viewport. |
[changeListener] | boolean | true | optional true : switch the keyboard focus to Handsontable. false : keep the previous keyboard focus. |
Returns: boolean
- true
: the selection was successful, false
: the selection failed.
selectCells
Source codecore.selectCells(coords, [scrollToCell], [changeListener]) ⇒ boolean
Select multiple cells or ranges of cells, adjacent or non-adjacent.
You can pass one of the below:
- An array of arrays (which matches the output of Handsontable's
getSelected()
method). - An array of
CellRange
objects (which matches the output of Handsontable'sgetSelectedRange()
method).
To select multiple cells, pass the visual row and column indexes of each cell, for example: hot.selectCells([[1, 1], [5, 5]])
.
To select multiple ranges, pass the visual indexes of the first and last cell in each range, for example: hot.selectCells([[1, 1, 2, 2], [6, 2, 0, 2]])
.
If your columns have properties, you can pass those properties' values instead of column indexes, for example: hot.selectCells([[1, 'first_name'], [5, 'last_name']])
.
By default, selectCell()
also:
- Scrolls the viewport to the newly-selected cells.
- Switches the keyboard focus to Handsontable (by calling Handsontable's
listen()
method).
Since: 0.38.0
Example
// select non-adjacent cells
hot.selectCells([[1, 1], [5, 5], [10, 10]]);
// select non-adjacent ranges of cells
hot.selectCells([[1, 1, 2, 2], [10, 10, 20, 20]]);
// select cells and ranges of cells
hot.selectCells([[1, 1, 2, 2], [3, 3], [6, 2, 0, 2]]);
// select cells, using column properties
hot.selectCells([[1, 'id', 2, 'first_name'], [3, 'full_name'], [6, 'last_name', 0, 'first_name']]);
// select multiple ranges, using an array of `CellRange` objects
const selected = hot.getSelectedRange();
selected[0].from.row = 0;
selected[0].from.col = 0;
selected[0].to.row = 5;
selected[0].to.col = 5;
selected[1].from.row = 10;
selected[1].from.col = 10;
selected[1].to.row = 20;
selected[1].to.col = 20;
hot.selectCells(selected);
Param | Type | Default | Description |
---|---|---|---|
coords | Array<Array> Array<CellRange> | Visual coordinates, passed either as an array of arrays ([[rowStart, columnStart, rowEnd, columnEnd], ...] ) or as an array of CellRange objects. | |
[scrollToCell] | boolean | true | optional true : scroll the viewport to the newly-selected cells. false : keep the previous viewport. |
[changeListener] | boolean | true | optional true : switch the keyboard focus to Handsontable. false : keep the previous keyboard focus. |
Returns: boolean
- true
: the selection was successful, false
: the selection failed.
selectColumns
Source codecore.selectColumns(startColumn, [endColumn], [focusPosition]) ⇒ boolean
Select column specified by startColumn
visual index, column property or a range of columns finishing at endColumn
.
Since: 0.38.0
Example
// Select column using visual index.
hot.selectColumns(1);
// Select column using column property.
hot.selectColumns('id');
// Select range of columns using visual indexes.
hot.selectColumns(1, 4);
// Select range of columns using visual indexes and mark the first header as highlighted.
hot.selectColumns(1, 2, -1);
// Select range of columns using visual indexes and mark the second cell as highlighted.
hot.selectColumns(2, 1, 1);
// Select range of columns using visual indexes and move the focus position somewhere in the middle of the range.
hot.selectColumns(2, 5, { row: 2, col: 3 });
// Select range of columns using column properties.
hot.selectColumns('id', 'last_name');
Param | Type | Default | Description |
---|---|---|---|
startColumn | number | The visual column index from which the selection starts. | |
[endColumn] | number | startColumn | optional The visual column index to which the selection finishes. If endColumn is not defined the column defined by startColumn will be selected. |
[focusPosition] | number Object CellCoords | 0 | optional The argument allows changing the cell/header focus position. The value can take visual row index from -N to N, where negative values point to the headers and positive values point to the cell range. An object with row and col properties also can be passed to change the focus position horizontally. |
Returns: boolean
- true
if selection was successful, false
otherwise.
selectRows
Source codecore.selectRows(startRow, [endRow], [focusPosition]) ⇒ boolean
Select row specified by startRow
visual index or a range of rows finishing at endRow
.
Since: 0.38.0
Example
// Select row using visual index.
hot.selectRows(1);
// select a range of rows, using visual indexes.
hot.selectRows(1, 4);
// select a range of rows, using visual indexes, and mark the header as highlighted.
hot.selectRows(1, 2, -1);
// Select range of rows using visual indexes and mark the second cell as highlighted.
hot.selectRows(2, 1, 1);
// Select range of rows using visual indexes and move the focus position somewhere in the middle of the range.
hot.selectRows(2, 5, { row: 2, col: 3 });
Param | Type | Default | Description |
---|---|---|---|
startRow | number | The visual row index from which the selection starts. | |
[endRow] | number | startRow | optional The visual row index to which the selection finishes. If endRow is not defined the row defined by startRow will be selected. |
[focusPosition] | number Object CellCoords | 0 | optional The argument allows changing the cell/header focus position. The value can take visual row index from -N to N, where negative values point to the headers and positive values point to the cell range. An object with row and col properties also can be passed to change the focus position vertically. |
Returns: boolean
- true
if selection was successful, false
otherwise.
setCellMeta
Source codecore.setCellMeta(row, column, key, value)
Sets a property defined by the key
property to the meta object of a cell corresponding to params row
and column
.
Emits: Hooks#event:beforeSetCellMeta
, Hooks#event:afterSetCellMeta
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
key | string | Property name. |
value | string | Property value. |
setCellMetaObject
Source codecore.setCellMetaObject(row, column, prop)
Set cell meta data object defined by prop
to the corresponding params row
and column
.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
column | number | Visual column index. |
prop | object | Meta object. |
setDataAtCell
Source codecore.setDataAtCell(row, [column], [value], [source])
Set new value to a cell. To change many cells at once (recommended way), pass an array of changes
in format
[[row, col, value],...]
as the first argument.
Param | Type | Description |
---|---|---|
row | number Array | Visual row index or array of changes in format [[row, col, value],...] . |
[column] | number | optional Visual column index. |
[value] | string | optional New value. |
[source] | string | optional String that identifies how this change will be described in the changes array (useful in afterChange or beforeChange callback). Set to 'edit' if left empty. |
setDataAtRowProp
Source codecore.setDataAtRowProp(row, prop, value, [source])
Set new value to a cell. To change many cells at once (recommended way), pass an array of changes
in format
[[row, prop, value],...]
as the first argument.
Param | Type | Description |
---|---|---|
row | number Array | Visual row index or array of changes in format [[row, prop, value], ...] . |
prop | string | Property name or the source string (e.g. 'first.name' or '0' ). |
value | string | Value to be set. |
[source] | string | optional String that identifies how this change will be described in changes array (useful in onChange callback). |
setSourceDataAtCell
Source codecore.setSourceDataAtCell(row, column, value, [source])
Set the provided value in the source data set at the provided coordinates.
Param | Type | Description |
---|---|---|
row | number Array | Physical row index or array of changes in format [[row, prop, value], ...] . |
column | number string | Physical column index / prop name. |
value | * | The value to be set at the provided coordinates. |
[source] | string | optional Source of the change as a string. |
spliceCellsMeta
Source codecore.spliceCellsMeta(visualIndex, [deleteAmount], [...cellMetaRows])
Removes or adds one or more rows of the cell meta objects to the cell meta collections.
Since: 0.30.0
Param | Type | Default | Description |
---|---|---|---|
visualIndex | number | A visual index that specifies at what position to add/remove items. | |
[deleteAmount] | number | 0 | optional The number of items to be removed. If set to 0, no cell meta objects will be removed. |
[...cellMetaRows] | object | optional The new cell meta row objects to be added to the cell meta collection. |
spliceCol
Source codecore.spliceCol(column, index, amount, [...elements]) ⇒ Array
Adds/removes data from the column. This method works the same as Array.splice for arrays.
Param | Type | Description |
---|---|---|
column | number | Index of the column in which do you want to do splice. |
index | number | Index at which to start changing the array. If negative, will begin that many elements from the end. |
amount | number | An integer indicating the number of old array elements to remove. If amount is 0, no elements are removed. |
[...elements] | number | optional The elements to add to the array. If you don't specify any elements, spliceCol simply removes elements from the array. |
Returns: Array
- Returns removed portion of columns.
spliceRow
Source codecore.spliceRow(row, index, amount, [...elements]) ⇒ Array
Adds/removes data from the row. This method works the same as Array.splice for arrays.
Param | Type | Description |
---|---|---|
row | number | Index of column in which do you want to do splice. |
index | number | Index at which to start changing the array. If negative, will begin that many elements from the end. |
amount | number | An integer indicating the number of old array elements to remove. If amount is 0, no elements are removed. |
[...elements] | number | optional The elements to add to the array. If you don't specify any elements, spliceCol simply removes elements from the array. |
Returns: Array
- Returns removed portion of rows.
suspendExecution
Source codecore.suspendExecution()
Suspends the execution process. It's helpful to wrap the table logic changes such as index changes into one call after which the cache is updated. As a result, it improves the performance of wrapped operations.
The method is intended to be used by advanced users. Suspending the execution process could cause visual glitches caused by not updated the internal table cache.
Since: 8.3.0
Example
hot.suspendExecution();
const filters = hot.getPlugin('filters');
filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
hot.resumeExecution(); // It updates the cache internally
suspendRender
Source codecore.suspendRender()
Suspends the rendering process. It's helpful to wrap the table render cycles triggered by API calls or UI actions (or both) and call the "render" once in the end. As a result, it improves the performance of wrapped operations. When the table is in the suspend state, most operations will have no visual effect until the rendering state is resumed. Resuming the state automatically invokes the table rendering. To make sure that after executing all operations, the table will be rendered, it's highly recommended to use the Core#batchRender method or Core#batch, which additionally aggregates the logic execution that happens behind the table.
The method is intended to be used by advanced users. Suspending the rendering process could cause visual glitches when wrongly implemented.
Every suspendRender()
call needs to correspond with one resumeRender()
call.
For example, if you call suspendRender()
5 times, you need to call resumeRender()
5 times as well.
Since: 8.3.0
Example
hot.suspendRender();
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 10, 40);
hot.setDataAtCell(1, 1, 'John');
hot.setDataAtCell(2, 2, 'Mark');
hot.setDataAtCell(3, 3, 'Ann');
hot.setDataAtCell(4, 4, 'Sophia');
hot.setDataAtCell(5, 5, 'Mia');
hot.selectCell(0, 0);
hot.resumeRender(); // It re-renders the table internally
toHTML
Source codecore.toHTML() ⇒ string
Converts instance into outerHTML of HTMLTableElement.
Since: 7.1.0
toPhysicalColumn
Source codecore.toPhysicalColumn(column) ⇒ number
Translate visual column index into physical.
This method is useful when you want to retrieve physical column index based on a visual index which can be reordered, moved or trimmed.
Param | Type | Description |
---|---|---|
column | number | Visual column index. |
Returns: number
- Returns physical column index.
toPhysicalRow
Source codecore.toPhysicalRow(row) ⇒ number
Translate visual row index into physical.
This method is useful when you want to retrieve physical row index based on a visual index which can be reordered, moved or trimmed.
Param | Type | Description |
---|---|---|
row | number | Visual row index. |
Returns: number
- Returns physical row index.
toTableElement
Source codecore.toTableElement() ⇒ HTMLTableElement
Converts instance into HTMLTableElement.
Since: 7.1.0
toVisualColumn
Source codecore.toVisualColumn(column) ⇒ number
Translate physical column index into visual.
This method is useful when you want to retrieve visual column index which can be reordered, moved or trimmed based on a physical index.
Param | Type | Description |
---|---|---|
column | number | Physical column index. |
Returns: number
- Returns visual column index.
toVisualRow
Source codecore.toVisualRow(row) ⇒ number
Translate physical row index into visual.
This method is useful when you want to retrieve visual row index which can be reordered, moved or trimmed based on a physical index.
Param | Type | Description |
---|---|---|
row | number | Physical row index. |
Returns: number
- Returns visual row index.
undo
Source codecore.undo() ⇒ boolean
unlisten
Source codecore.unlisten()
Stop listening to keyboard input on the document body. Calling this method makes the Handsontable inactive for any keyboard events.
updateData
Source codecore.updateData(data, [source])
The updateData()
method replaces Handsontable's data
with a new dataset.
The updateData()
method:
- Keeps cells' states (e.g. cells' formatting and cells'
readOnly
states) - Keeps rows' states (e.g. row order)
- Keeps columns' states (e.g. column order)
To replace Handsontable's data
and reset states, use the loadData()
method.
Read more:
Emits: Hooks#event:beforeUpdateData
, Hooks#event:afterUpdateData
, Hooks#event:afterChange
Since: 11.1.0
Param | Type | Description |
---|---|---|
data | Array | An array of arrays, or an array of objects, that contains Handsontable's data |
[source] | string | optional The source of the updateData() call |
updateSettings
Source codecore.updateSettings(settings, [init])
Use it if you need to change configuration after initialization. The settings
argument is an object containing the changed
settings, declared the same way as in the initial settings object.
Note, that although the updateSettings
method doesn't overwrite the previously declared settings, it might reset
the settings made post-initialization. (for example - ignore changes made using the columnResize feature).
Since 8.0.0 passing columns
or data
inside settings
objects will result in resetting states corresponding to rows and columns
(for example, row/column sequence, column width, row height, frozen columns etc.).
Since 12.0.0 passing data
inside settings
objects no longer results in resetting states corresponding to rows and columns
(for example, row/column sequence, column width, row height, frozen columns etc.).
Emits: Hooks#event:afterCellMetaReset
, Hooks#event:afterUpdateSettings
Example
hot.updateSettings({
contextMenu: true,
colHeaders: true,
fixedRowsTop: 2
});
Param | Type | Default | Description |
---|---|---|---|
settings | object | A settings object (see Options). Only provide the settings that are changed, not the whole settings object that was used for initialization. | |
[init] | boolean | false | optional Internally used for in initialization mode. |
validateCell
Source codecore.validateCell(value, cellProperties, callback, source)
Validate a single cell.
Param | Type | Description |
---|---|---|
value | string number | The value to validate. |
cellProperties | object | The cell meta which corresponds with the value. |
callback | function | The callback function. |
source | string | The string that identifies source of the validation. |
validateCells
Source codecore.validateCells([callback])
Validates every cell in the data set, using a validator function configured for each cell.
Doesn't validate cells that are currently trimmed, hidden, or filtered, as such cells are not included in the data set until you bring them back again.
After the validation, the callback
function is fired, with the valid
argument set to:
true
for valid cellsfalse
for invalid cells
Example
hot.validateCells((valid) => {
if (valid) {
// ... code for validated cells
}
})
Param | Type | Description |
---|---|---|
[callback] | function | optional The callback function. |
validateColumns
Source codecore.validateColumns([columns], [callback])
Validates columns using their validator functions and calls callback when finished.
If one of the cells is invalid, the callback will be fired with 'valid'
arguments as false
- otherwise it
would equal true
.
Example
hot.validateColumns([3, 4, 5], (valid) => {
if (valid) {
// ... code for validated columns
}
})
Param | Type | Description |
---|---|---|
[columns] | Array | optional Array of validation target visual columns indexes. |
[callback] | function | optional The callback function. |
validateRows
Source codecore.validateRows([rows], [callback])
Validates rows using their validator functions and calls callback when finished.
If one of the cells is invalid, the callback will be fired with 'valid'
arguments as false
- otherwise it
would equal true
.
Example
hot.validateRows([3, 4, 5], (valid) => {
if (valid) {
// ... code for validated rows
}
})
Param | Type | Description |
---|---|---|
[rows] | Array | optional Array of validation target visual row indexes. |
[callback] | function | optional The callback function. |