handsontable
Version:
Handsontable is a JavaScript Spreadsheet Component available for React, Angular and Vue.
1,216 lines (1,193 loc) • 104 kB
JavaScript
"use strict";
require("core-js/modules/es.array.slice.js");
require("core-js/modules/es.object.freeze.js");
exports.__esModule = true;
exports.default = void 0;
require("core-js/modules/es.array.iterator.js");
require("core-js/modules/es.map.js");
require("core-js/modules/es.object.to-string.js");
require("core-js/modules/es.string.iterator.js");
require("core-js/modules/web.dom-collections.iterator.js");
require("core-js/modules/es.array.index-of.js");
require("core-js/modules/es.array.splice.js");
var _array = require("./helpers/array");
var _object = require("./helpers/object");
var _string = require("./helpers/string");
var _console = require("./helpers/console");
var _templateLiteralTag = require("./helpers/templateLiteralTag");
var _function = require("./helpers/function");
var _templateObject;
function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }
function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(0); } return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
/**
* @description
* Handsontable events are the common interface that function in 2 ways: as __callbacks__ and as __hooks__.
*
* @example
*
* ```js
* // Using events as callbacks:
* ...
* const hot1 = new Handsontable(document.getElementById('example1'), {
* afterChange: function(changes, source) {
* $.ajax({
* url: "save.php',
* data: change
* });
* }
* });
* ...
* ```
*
* ```js
* // Using events as plugin hooks:
* ...
* const hot1 = new Handsontable(document.getElementById('example1'), {
* myPlugin: true
* });
*
* const hot2 = new Handsontable(document.getElementById('example2'), {
* myPlugin: false
* });
*
* // global hook
* Handsontable.hooks.add('afterChange', function() {
* // Fired twice - for hot1 and hot2
* if (this.getSettings().myPlugin) {
* // function body - will only run for hot1
* }
* });
*
* // local hook (has same effect as a callback)
* hot2.addHook('afterChange', function() {
* // function body - will only run in #example2
* });
* ```
* ...
*/
// @TODO: Move plugin description hooks to plugin?
var REGISTERED_HOOKS = [
/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* Fired after resetting a cell's meta. This happens when the {@link Core#updateSettings} method is called.
*
* @event Hooks#afterCellMetaReset
*/
'afterCellMetaReset',
/**
* Fired after one or more cells has been changed. The changes are triggered in any situation when the
* value is entered using an editor or changed using API (e.q setDataAtCell).
*
* __Note:__ For performance reasons, the `changes` array is null for `"loadData"` source.
*
* @event Hooks#afterChange
* @param {Array} changes 2D array containing information about each of the edited cells `[[row, prop, oldVal, newVal], ...]`.
* @param {string} [source] String that identifies source of hook call ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @example
* ```js
* new Handsontable(element, {
* afterChange: (changes) => {
* changes.forEach(([row, prop, oldValue, newValue]) => {
* // Some logic...
* });
* }
* })
* ```
*/
'afterChange',
/**
* Fired each time user opens {@link ContextMenu} and after setting up the Context Menu's default options. These options are a collection
* which user can select by setting an array of keys or an array of objects in {@link Options#contextMenu} option.
*
* @event Hooks#afterContextMenuDefaultOptions
* @param {Array} predefinedItems An array of objects containing information about the pre-defined Context Menu items.
*/
'afterContextMenuDefaultOptions',
/**
* Fired each time user opens {@link ContextMenu} plugin before setting up the Context Menu's items but after filtering these options by
* user (`contextMenu` option). This hook can by helpful to determine if user use specified menu item or to set up
* one of the menu item to by always visible.
*
* @event Hooks#beforeContextMenuSetItems
* @param {object[]} menuItems An array of objects containing information about to generated Context Menu items.
*/
'beforeContextMenuSetItems',
/**
* Fired by {@link DropdownMenu} plugin after setting up the Dropdown Menu's default options. These options are a
* collection which user can select by setting an array of keys or an array of objects in {@link Options#dropdownMenu}
* option.
*
* @event Hooks#afterDropdownMenuDefaultOptions
* @param {object[]} predefinedItems An array of objects containing information about the pre-defined Context Menu items.
*/
'afterDropdownMenuDefaultOptions',
/**
* Fired by {@link DropdownMenu} plugin before setting up the Dropdown Menu's items but after filtering these options
* by user (`dropdownMenu` option). This hook can by helpful to determine if user use specified menu item or to set
* up one of the menu item to by always visible.
*
* @event Hooks#beforeDropdownMenuSetItems
* @param {object[]} menuItems An array of objects containing information about to generated Dropdown Menu items.
*/
'beforeDropdownMenuSetItems',
/**
* Fired by {@link ContextMenu} plugin after hiding the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#afterContextMenuHide
* @param {object} context The Context Menu plugin instance.
*/
'afterContextMenuHide',
/**
* Fired by {@link ContextMenu} plugin before opening the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#beforeContextMenuShow
* @param {object} context The Context Menu instance.
*/
'beforeContextMenuShow',
/**
* Fired by {@link ContextMenu} plugin after opening the Context Menu. This hook is fired when {@link Options#contextMenu}
* option is enabled.
*
* @event Hooks#afterContextMenuShow
* @param {object} context The Context Menu plugin instance.
*/
'afterContextMenuShow',
/**
* Fired by {@link CopyPaste} plugin after reaching the copy limit while copying data. This hook is fired when
* {@link Options#copyPaste} option is enabled.
*
* @event Hooks#afterCopyLimit
* @param {number} selectedRows Count of selected copyable rows.
* @param {number} selectedColumns Count of selected copyable columns.
* @param {number} copyRowsLimit Current copy rows limit.
* @param {number} copyColumnsLimit Current copy columns limit.
*/
'afterCopyLimit',
/**
* Fired before created a new column.
*
* @event Hooks#beforeCreateCol
* @param {number} index Represents the visual index of first newly created column in the data source array.
* @param {number} amount Number of newly created columns in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {*} If `false` then creating columns is cancelled.
* @example
* ```js
* // Return `false` to cancel column inserting.
* new Handsontable(element, {
* beforeCreateCol: function(data, coords) {
* return false;
* }
* });
* ```
*/
'beforeCreateCol',
/**
* Fired after created a new column.
*
* @event Hooks#afterCreateCol
* @param {number} index Represents the visual index of first newly created column in the data source.
* @param {number} amount Number of newly created columns in the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterCreateCol',
/**
* Fired before created a new row.
*
* @event Hooks#beforeCreateRow
* @param {number} index Represents the visual index of first newly created row in the data source array.
* @param {number} amount Number of newly created rows in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeCreateRow',
/**
* Fired after created a new row.
*
* @event Hooks#afterCreateRow
* @param {number} index Represents the visual index of first newly created row in the data source array.
* @param {number} amount Number of newly created rows in the data source array.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterCreateRow',
/**
* Fired after the current cell is deselected.
*
* @event Hooks#afterDeselect
*/
'afterDeselect',
/**
* Fired after destroying the Handsontable instance.
*
* @event Hooks#afterDestroy
*/
'afterDestroy',
/**
* Hook fired after keydown event is handled.
*
* @event Hooks#afterDocumentKeyDown
* @param {Event} event A native `keydown` event object.
*/
'afterDocumentKeyDown',
/**
* Fired inside the Walkontable's selection `draw` method. Can be used to add additional class names to cells, depending on the current selection.
*
* @event Hooks#afterDrawSelection
* @param {number} currentRow Row index of the currently processed cell.
* @param {number} currentColumn Column index of the currently cell.
* @param {number[]} cornersOfSelection Array of the current selection in a form of `[startRow, startColumn, endRow, endColumn]`.
* @param {number|undefined} layerLevel Number indicating which layer of selection is currently processed.
* @since 0.38.1
* @returns {string|undefined} Can return a `String`, which will act as an additional `className` to be added to the currently processed cell.
*/
'afterDrawSelection',
/**
* Fired inside the Walkontable's `refreshSelections` method. Can be used to remove additional class names from all cells in the table.
*
* @event Hooks#beforeRemoveCellClassNames
* @since 0.38.1
* @returns {string[]|undefined} Can return an `Array` of `String`s. Each of these strings will act like class names to be removed from all the cells in the table.
*/
'beforeRemoveCellClassNames',
/**
* Fired after getting the cell settings.
*
* @event Hooks#afterGetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {object} cellProperties Object containing the cell properties.
*/
'afterGetCellMeta',
/**
* Fired after retrieving information about a column header and appending it to the table header.
*
* @event Hooks#afterGetColHeader
* @param {number} column Visual column index.
* @param {HTMLTableCellElement} TH Header's TH element.
*/
'afterGetColHeader',
/**
* Fired after retrieving information about a row header and appending it to the table header.
*
* @event Hooks#afterGetRowHeader
* @param {number} row Visual row index.
* @param {HTMLTableCellElement} TH Header's TH element.
*/
'afterGetRowHeader',
/**
* Fired after the Handsontable instance is initiated.
*
* @event Hooks#afterInit
*/
'afterInit',
/**
* Fired after Handsontable's [`data`](@/api/options.md#data)
* gets modified by the [`loadData()`](@/api/core.md#loaddata) method
* or the [`updateSettings()`](@/api/core.md#updatesettings) method.
*
* Read more:
* - [Binding to data →](@/guides/getting-started/binding-to-data.md)
* - [Saving data →](@/guides/getting-started/saving-data.md)
*
* @event Hooks#afterLoadData
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
*/
'afterLoadData',
/**
* Fired after the [`updateData()`](@/api/core.md#updatedata) method
* modifies Handsontable's [`data`](@/api/options.md#data).
*
* Read more:
* - [Binding to data →](@/guides/getting-started/binding-to-data.md)
* - [Saving data →](@/guides/getting-started/saving-data.md)
*
* @event Hooks#afterUpdateData
* @since 11.1.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
*/
'afterUpdateData',
/**
* Fired after a scroll event, which is identified as a momentum scroll (e.g. On an iPad).
*
* @event Hooks#afterMomentumScroll
*/
'afterMomentumScroll',
/**
* Fired after a `mousedown` event is triggered on the cell corner (the drag handle).
*
* @event Hooks#afterOnCellCornerMouseDown
* @param {Event} event `mousedown` event object.
*/
'afterOnCellCornerMouseDown',
/**
* Fired after a `dblclick` event is triggered on the cell corner (the drag handle).
*
* @event Hooks#afterOnCellCornerDblClick
* @param {Event} event `dblclick` event object.
*/
'afterOnCellCornerDblClick',
/**
* Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate
* indexes are negative.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellMouseDown` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseDown
* @param {Event} event `mousedown` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseDown',
/**
* Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate
* indexes are negative.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellMouseUp` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseUp
* @param {Event} event `mouseup` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseUp',
/**
* Fired after clicking right mouse button on a cell or row/column header.
*
* For example clicking on the row header of cell (0, 0) results with `afterOnCellContextMenu` called
* with coordinates `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellContextMenu
* @since 4.1.0
* @param {Event} event `contextmenu` event object.
* @param {CellCoords} coords Coordinates object containing the visual row and visual column indexes of the clicked cell.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellContextMenu',
/**
* Fired after hovering a cell or row/column header with the mouse cursor. In case the row/column header was
* hovered, the index is negative.
*
* For example, hovering over the row header of cell (0, 0) results with `afterOnCellMouseOver` called
* with coords `{row: 0, col: -1}`.
*
* @event Hooks#afterOnCellMouseOver
* @param {Event} event `mouseover` event object.
* @param {CellCoords} coords Hovered cell's visual coordinate object.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseOver',
/**
* Fired after leaving a cell or row/column header with the mouse cursor.
*
* @event Hooks#afterOnCellMouseOut
* @param {Event} event `mouseout` event object.
* @param {CellCoords} coords Leaved cell's visual coordinate object.
* @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
*/
'afterOnCellMouseOut',
/**
* Fired after one or more columns are removed.
*
* @event Hooks#afterRemoveCol
* @param {number} index Visual index of starter column.
* @param {number} amount An amount of removed columns.
* @param {number[]} physicalColumns An array of physical columns removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterRemoveCol',
/**
* Fired after one or more rows are removed.
*
* @event Hooks#afterRemoveRow
* @param {number} index Visual index of starter row.
* @param {number} amount An amount of removed rows.
* @param {number[]} physicalRows An array of physical rows removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterRemoveRow',
/**
* Fired before starting rendering the cell.
*
* @event Hooks#beforeRenderer
* @param {HTMLTableCellElement} TD Currently rendered cell's TD element.
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string|number} prop Column property name or a column index, if datasource is an array of arrays.
* @param {*} value Value of the rendered cell.
* @param {object} cellProperties Object containing the cell's properties.
*/
'beforeRenderer',
/**
* Fired after finishing rendering the cell (after the renderer finishes).
*
* @event Hooks#afterRenderer
* @param {HTMLTableCellElement} TD Currently rendered cell's TD element.
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string|number} prop Column property name or a column index, if datasource is an array of arrays.
* @param {*} value Value of the rendered cell.
* @param {object} cellProperties Object containing the cell's properties.
*/
'afterRenderer',
/**
* Fired after the horizontal scroll event.
*
* @event Hooks#afterScrollHorizontally
*/
'afterScrollHorizontally',
/**
* Fired after the vertical scroll event.
*
* @event Hooks#afterScrollVertically
*/
'afterScrollVertically',
/**
* Fired after one or more cells are selected (e.g. During mouse move).
*
* @event Hooks#afterSelection
* @param {number} row Selection start visual row index.
* @param {number} column Selection start visual column index.
* @param {number} row2 Selection end visual row index.
* @param {number} column2 Selection end visual column index.
* @param {object} preventScrolling A reference to the observable object with the `value` property.
* Property `preventScrolling.value` expects a boolean value that
* Handsontable uses to control scroll behavior after selection.
* @param {object} preventScrolling Object with `value` property where its value change will be observed.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
* @example
* ```js
* new Handsontable(element, {
* afterSelection: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // If set to `false` (default): when cell selection is outside the viewport,
* // Handsontable scrolls the viewport to cell selection's end corner.
* // If set to `true`: when cell selection is outside the viewport,
* // Handsontable doesn't scroll to cell selection's end corner.
* preventScrolling.value = true;
* }
* })
* ```
*/
'afterSelection',
/**
* Fired after one or more cells are selected.
*
* The `prop` and `prop2` arguments represent the source object property name instead of the column number.
*
* @event Hooks#afterSelectionByProp
* @param {number} row Selection start visual row index.
* @param {string} prop Selection start data source object property name.
* @param {number} row2 Selection end visual row index.
* @param {string} prop2 Selection end data source object property name.
* @param {object} preventScrolling Object with `value` property where its value change will be observed.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
* @example
* ```js
* new Handsontable(element, {
* afterSelectionByProp: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
* // setting if prevent scrolling after selection
* preventScrolling.value = true;
* }
* })
* ```
*/
'afterSelectionByProp',
/**
* Fired after one or more cells are selected (e.g. On mouse up).
*
* @event Hooks#afterSelectionEnd
* @param {number} row Selection start visual row index.
* @param {number} column Selection start visual column index.
* @param {number} row2 Selection end visual row index.
* @param {number} column2 Selection end visual column index.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
*/
'afterSelectionEnd',
/**
* Fired after one or more cells are selected (e.g. On mouse up).
*
* The `prop` and `prop2` arguments represent the source object property name instead of the column number.
*
* @event Hooks#afterSelectionEndByProp
* @param {number} row Selection start visual row index.
* @param {string} prop Selection start data source object property index.
* @param {number} row2 Selection end visual row index.
* @param {string} prop2 Selection end data source object property index.
* @param {number} selectionLayerLevel The number which indicates what selection layer is currently modified.
*/
'afterSelectionEndByProp',
/**
* Fired after cell meta is changed.
*
* @event Hooks#afterSetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The updated meta key.
* @param {*} value The updated meta value.
*/
'afterSetCellMeta',
/**
* Fired after cell meta is removed.
*
* @event Hooks#afterRemoveCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The removed meta key.
* @param {*} value Value which was under removed key of cell meta.
*/
'afterRemoveCellMeta',
/**
* Fired after cell data was changed.
*
* @event Hooks#afterSetDataAtCell
* @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterSetDataAtCell',
/**
* Fired after cell data was changed.
* Called only when `setDataAtRowProp` was executed.
*
* @event Hooks#afterSetDataAtRowProp
* @param {Array} changes An array of changes in format `[[row, prop, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'afterSetDataAtRowProp',
/**
* Fired after cell source data was changed.
*
* @event Hooks#afterSetSourceDataAtCell
* @since 8.0.0
* @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
* @param {string} [source] String that identifies source of hook call.
*/
'afterSetSourceDataAtCell',
/**
* Fired after calling the `updateSettings` method.
*
* @event Hooks#afterUpdateSettings
* @param {object} newSettings New settings object.
*/
'afterUpdateSettings',
/**
* @description
* A plugin hook executed after validator function, only if validator function is defined.
* Validation result is the first parameter. This can be used to determinate if validation passed successfully or not.
*
* __Returning false from the callback will mark the cell as invalid__.
*
* @event Hooks#afterValidate
* @param {boolean} isValid `true` if valid, `false` if not.
* @param {*} value The value in question.
* @param {number} row Visual row index.
* @param {string|number} prop Property name / visual column index.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {void | boolean} If `false` the cell will be marked as invalid, `true` otherwise.
*/
'afterValidate',
/**
* Fired before successful change of language (when proper language code was set).
*
* @event Hooks#beforeLanguageChange
* @since 0.35.0
* @param {string} languageCode New language code.
*/
'beforeLanguageChange',
/**
* Fired after successful change of language (when proper language code was set).
*
* @event Hooks#afterLanguageChange
* @since 0.35.0
* @param {string} languageCode New language code.
*/
'afterLanguageChange',
/**
* Fired by {@link Autofill} plugin before populating the data in the autofill feature. This hook is fired when
* {@link Options#fillHandle} option is enabled.
*
* @event Hooks#beforeAutofill
* @param {Array[]} selectionData Data the autofill operation will start from.
* @param {CellRange} sourceRange The range values will be filled from.
* @param {CellRange} targetRange The range new values will be filled into.
* @param {string} direction Declares the direction of the autofill. Possible values: `up`, `down`, `left`, `right`.
*
* @returns {boolean|Array[]} If false, the operation is cancelled. If array of arrays, the returned data
* will be passed into `populateFromArray` instead of the default autofill
* algorithm's result.
*/
'beforeAutofill',
/**
* Fired by {@link Autofill} plugin after populating the data in the autofill feature. This hook is fired when
* {@link Options#fillHandle} option is enabled.
*
* @event Hooks#afterAutofill
* @since 8.0.0
* @param {Array[]} fillData The data that was used to fill the `targetRange`. If `beforeAutofill` was used
* and returned `[[]]`, this will be the same object that was returned from `beforeAutofill`.
* @param {CellRange} sourceRange The range values will be filled from.
* @param {CellRange} targetRange The range new values will be filled into.
* @param {string} direction Declares the direction of the autofill. Possible values: `up`, `down`, `left`, `right`.
*/
'afterAutofill',
/**
* Fired before aligning the cell contents.
*
* @event Hooks#beforeCellAlignment
* @param {object} stateBefore An object with class names defining the cell alignment.
* @param {CellRange[]} range An array of CellRange coordinates where the alignment will be applied.
* @param {string} type Type of the alignment - either `horizontal` or `vertical`.
* @param {string} alignmentClass String defining the alignment class added to the cell.
* Possible values:
* * `htLeft`
* * `htCenter`
* * `htRight`
* * `htJustify`
* * `htTop`
* * `htMiddle`
* * `htBottom`.
*/
'beforeCellAlignment',
/**
* Fired before one or more cells is changed. Its main purpose is to alter changes silently after input and before
* table rendering.
*
* @event Hooks#beforeChange
* @param {Array[]} changes 2D array containing information about each of the edited cells.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {void | boolean} If `false` all changes were cancelled, `true` otherwise.
* @example
* ```js
* // To disregard a single change, set changes[i] to null or remove it from array using changes.splice(i, 1).
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0] = null;
* }
* });
* // To alter a single change, overwrite the desired value to changes[i][3].
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* changes[0][3] = 10;
* }
* });
* // To cancel all edit, return false from the callback or set array length to 0 (changes.length = 0).
* new Handsontable(element, {
* beforeChange: (changes, source) => {
* // [[row, prop, oldVal, newVal], ...]
* return false;
* }
* });
* ```
*/
'beforeChange',
/**
* Fired right before rendering the changes.
*
* @event Hooks#beforeChangeRender
* @param {Array[]} changes Array in form of `[row, prop, oldValue, newValue]`.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'beforeChangeRender',
/**
* Fired before drawing the borders.
*
* @event Hooks#beforeDrawBorders
* @param {Array} corners Array specifying the current selection borders.
* @param {string} borderClassName Specifies the border class name.
*/
'beforeDrawBorders',
/**
* Fired before getting cell settings.
*
* @event Hooks#beforeGetCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {object} cellProperties Object containing the cell's properties.
*/
'beforeGetCellMeta',
/**
* Fired before cell meta is removed.
*
* @event Hooks#beforeRemoveCellMeta
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The removed meta key.
* @param {*} value Value which is under removed key of cell meta.
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeRemoveCellMeta',
/**
* Fired before the Handsontable instance is initiated.
*
* @event Hooks#beforeInit
*/
'beforeInit',
/**
* Fired before the Walkontable instance is initiated.
*
* @event Hooks#beforeInitWalkontable
* @param {object} walkontableConfig Walkontable configuration object.
*/
'beforeInitWalkontable',
/**
* Fired before Handsontable's [`data`](@/api/options.md#data)
* gets modified by the [`loadData()`](@/api/core.md#loaddata) method
* or the [`updateSettings()`](@/api/core.md#updatesettings) method.
*
* Read more:
* - [Binding to data →](@/guides/getting-started/binding-to-data.md)
* - [Saving data →](@/guides/getting-started/saving-data.md)
*
* @event Hooks#beforeLoadData
* @since 8.0.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
* @returns {Array} The returned array will be used as Handsontable's new dataset.
*/
'beforeLoadData',
/**
* Fired before the [`updateData()`](@/api/core.md#updatedata) method
* modifies Handsontable's [`data`](@/api/options.md#data).
*
* Read more:
* - [Binding to data →](@/guides/getting-started/binding-to-data.md)
* - [Saving data →](@/guides/getting-started/saving-data.md)
*
* @event Hooks#beforeUpdateData
* @since 11.1.0
* @param {Array} sourceData An [array of arrays](@/guides/getting-started/binding-to-data.md#array-of-arrays), or an [array of objects](@/guides/getting-started/binding-to-data.md#array-of-objects), that contains Handsontable's data
* @param {boolean} initialLoad A flag that indicates whether the data was loaded at Handsontable's initialization (`true`) or later (`false`)
* @param {string} source The source of the call
* @returns {Array} The returned array will be used as Handsontable's new dataset.
*/
'beforeUpdateData',
/**
* Hook fired before keydown event is handled. It can be used to stop default key bindings.
*
* __Note__: To prevent default behavior you need to call `false` in your `beforeKeyDown` handler.
*
* @event Hooks#beforeKeyDown
* @param {Event} event Original DOM event.
*/
'beforeKeyDown',
/**
* Fired after the user clicked a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseDown
* @param {Event} event The `mousedown` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
* @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
* a boolean value that allows or disallows changing the selection for that particular area.
*/
'beforeOnCellMouseDown',
/**
* Fired after the user clicked a cell.
*
* @event Hooks#beforeOnCellMouseUp
* @param {Event} event The `mouseup` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
*/
'beforeOnCellMouseUp',
/**
* Fired after the user clicked a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellContextMenu
* @since 4.1.0
* @param {Event} event The `contextmenu` event object.
* @param {CellCoords} coords Cell coords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
*/
'beforeOnCellContextMenu',
/**
* Fired after the user moved cursor over a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseOver
* @param {Event} event The `mouseover` event object.
* @param {CellCoords} coords CellCoords object containing the visual coordinates of the clicked cell.
* @param {HTMLTableCellElement} TD TD element.
* @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
* a boolean value that allows or disallows changing the selection for that particular area.
*/
'beforeOnCellMouseOver',
/**
* Fired after the user moved cursor out from a cell, but before all the calculations related with it.
*
* @event Hooks#beforeOnCellMouseOut
* @param {Event} event The `mouseout` event object.
* @param {CellCoords} coords CellCoords object containing the visual coordinates of the leaved cell.
* @param {HTMLTableCellElement} TD TD element.
*/
'beforeOnCellMouseOut',
/**
* Fired before one or more columns are about to be removed.
*
* @event Hooks#beforeRemoveCol
* @param {number} index Visual index of starter column.
* @param {number} amount Amount of columns to be removed.
* @param {number[]} physicalColumns An array of physical columns removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeRemoveCol',
/**
* Fired when one or more rows are about to be removed.
*
* @event Hooks#beforeRemoveRow
* @param {number} index Visual index of starter row.
* @param {number} amount Amount of rows to be removed.
* @param {number[]} physicalRows An array of physical rows removed from the data source.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeRemoveRow',
/**
* Fired before Handsontable's view-rendering engine is rendered.
*
* __Note:__ In Handsontable 9.x and earlier, the `beforeViewRender` hook was named `beforeRender`.
*
* @event Hooks#beforeViewRender
* @since 10.0.0
* @param {boolean} isForced If set to `true`, the rendering gets triggered by a change of settings, a change of
* data, or a logic that needs a full Handsontable render cycle.
* If set to `false`, the rendering gets triggered by scrolling or moving the selection.
* @param {object} skipRender Object with `skipRender` property, if it is set to `true ` the next rendering cycle will be skipped.
*/
'beforeViewRender',
/**
* Fired after Handsontable's view-rendering engine is rendered,
* but before redrawing the selection borders and before scroll syncing.
*
* __Note:__ In Handsontable 9.x and earlier, the `afterViewRender` hook was named `afterRender`.
*
* @event Hooks#afterViewRender
* @since 10.0.0
* @param {boolean} isForced If set to `true`, the rendering gets triggered by a change of settings, a change of
* data, or a logic that needs a full Handsontable render cycle.
* If set to `false`, the rendering gets triggered by scrolling or moving the selection.
*/
'afterViewRender',
/**
* Fired before Handsontable's view-rendering engine updates the view.
*
* The `beforeRender` event is fired right after the Handsontable
* business logic is executed and right before the rendering engine starts calling
* the Core logic, renderers, cell meta objects etc. to update the view.
*
* @event Hooks#beforeRender
* @param {boolean} isForced If set to `true`, the rendering gets triggered by a change of settings, a change of
* data, or a logic that needs a full Handsontable render cycle.
* If set to `false`, the rendering gets triggered by scrolling or moving the selection.
*/
'beforeRender',
/**
* Fired after Handsontable's view-rendering engine updates the view.
*
* @event Hooks#afterRender
* @param {boolean} isForced If set to `true`, the rendering gets triggered by a change of settings, a change of
* data, or a logic that needs a full Handsontable render cycle.
* If set to `false`, the rendering gets triggered by scrolling or moving the selection.
*/
'afterRender',
/**
* Fired before cell meta is changed.
*
* @event Hooks#beforeSetCellMeta
* @since 8.0.0
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {string} key The updated meta key.
* @param {*} value The updated meta value.
* @returns {*|boolean} If false is returned the action is canceled.
*/
'beforeSetCellMeta',
/**
* Fired before setting range is started but not finished yet.
*
* @event Hooks#beforeSetRangeStartOnly
* @param {CellCoords} coords CellCoords instance.
*/
'beforeSetRangeStartOnly',
/**
* Fired before setting range is started.
*
* @event Hooks#beforeSetRangeStart
* @param {CellCoords} coords CellCoords instance.
*/
'beforeSetRangeStart',
/**
* Fired before setting range is ended.
*
* @event Hooks#beforeSetRangeEnd
* @param {CellCoords} coords CellCoords instance.
*/
'beforeSetRangeEnd',
/**
* Fired before the logic of handling a touch scroll, when user started scrolling on a touch-enabled device.
*
* @event Hooks#beforeTouchScroll
*/
'beforeTouchScroll',
/**
* Fired before cell validation, only if validator function is defined. This can be used to manipulate the value
* of changed cell before it is applied to the validator function.
*
* __Note:__ this will not affect values of changes. This will change value *ONLY* for validation.
*
* @event Hooks#beforeValidate
* @param {*} value Value of the cell.
* @param {number} row Visual row index.
* @param {string|number} prop Property name / column index.
* @param {string} [source] String that identifies source of hook call
* ([list of all available sources](@/guides/getting-started/events-and-hooks.md#definition-for-source-argument)).
*/
'beforeValidate',
/**
* Fired before cell value is rendered into the DOM (through renderer function). This can be used to manipulate the
* value which is passed to the renderer without modifying the renderer itself.
*
* @event Hooks#beforeValueRender
* @param {*} value Cell value to render.
* @param {object} cellProperties An object containing the cell properties.
*/
'beforeValueRender',
/**
* Fired after Handsontable instance is constructed (using `new` operator).
*
* @event Hooks#construct
*/
'construct',
/**
* Fired after Handsontable instance is initiated but before table is rendered.
*
* @event Hooks#init
*/
'init',
/**
* Fired when a column header index is about to be modified by a callback function.
*
* @event Hooks#modifyColHeader
* @param {number} column Visual column header index.
*/
'modifyColHeader',
/**
* Fired when a column width is about to be modified by a callback function.
*
* @event Hooks#modifyColWidth
* @param {number} width Current column width.
* @param {number} column Visual column index.
*/
'modifyColWidth',
/**
* Fired when a row header index is about to be modified by a callback function.
*
* @event Hooks#modifyRowHeader
* @param {number} row Visual row header index.
*/
'modifyRowHeader',
/**
* Fired when a row height is about to be modified by a callback function.
*
* @event Hooks#modifyRowHeight
* @param {number} height Row height.
* @param {number} row Visual row index.
*/
'modifyRowHeight',
/**
* Fired when a data was retrieved or modified.
*
* @event Hooks#modifyData
* @param {number} row Physical row height.
* @param {number} column Physical column index.
* @param {object} valueHolder Object which contains original value which can be modified by overwriting `.value` property.
* @param {string} ioMode String which indicates for what operation hook is fired (`get` or `set`).
*/
'modifyData',
/**
* Fired when a data was retrieved or modified from the source data set.
*
* @event Hooks#modifySourceData
* @since 8.0.0
* @param {number} row Physical row index.
* @param {number} column Physical column index.
* @param {object} valueHolder Object which contains original value which can be modified by overwriting `.value` property.
* @param {string} ioMode String which indicates for what operation hook is fired (`get` or `set`).
*/
'modifySourceData',
/**
* Fired when a data was retrieved or modified.
*
* @event Hooks#modifyRowData
* @param {number} row Physical row index.
*/
'modifyRowData',
/**
* Used to modify the cell coordinates when using the `getCell` method, opening editor, getting value from the editor
* and saving values from the closed editor.
*
* @event Hooks#modifyGetCellCoords
* @since 0.36.0
* @param {number} row Visual row index.
* @param {number} column Visual column index.
* @param {boolean} topmost 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.
*/
'modifyGetCellCoords',
/**
* Allows modify the visual row index that is used to retrieve the row header element (TH) before it's
* highlighted (proper CSS class names are added). Modifying the visual row index allows building a custom
* implementation of the nested headers feature or other features that require highlighting other DOM
* elements than that the rendering engine, by default, would have highlighted.
*
* @event Hooks#beforeHighlightingRowHeader
* @since 8.4.0
* @param {number} row Visual row index.
* @param {number} headerLevel Column header level (0 = most distant to the table).
* @param {object} highlightMeta An object that contains additional information about processed selection.
* @returns {number|undefined}
*/
'beforeHighlightingRowHeader',
/**
* Allows modify the visual column index that is used to retrieve the column header element (TH) before it's
* highlighted (proper CSS class names are added). Modifying the visual column index allows building a custom
* implementation of the nested headers feature or other features that require highlighting other DOM
* elements than that the rendering engine, by default, would have highlighted.
*
* @event Hooks#beforeHighlightingColumnHeader
* @since 8.4.0
* @param {number} column Visual column index.
* @param {number} headerLevel Row header level (0 = most distant to the table).
* @param {object} highlightMeta An object that contains additional information about processed selection.
* @returns {number|undefined}
*/
'beforeHighlightingColumnHeader',
/**
* Fired by {@link PersistentState} plugin, after loading value, saved under given key, from browser local storage. This hook is fired when
* {@link Options#persistentState} option is enabled.
*
* @event Hooks#persistentStateLoad
* @param {string} key Key.
* @param {object} valuePlaceholder Object containing the loaded value under `valuePlaceholder.value` (if no value have been saved, `value` key will be undefined).
*/
'persistentStateLoad',
/**
* Fired by {@link PersistentState} plugin after resetting data from local storage. If no key is given, all values associated with table will be cleared.
* This hook is fired when {@link Options#persistentState} option is enabled.
*
* @event Hooks#persistentStateReset
* @param {string} [key] Key.
*/
'persistentStateReset',
/**
* Fired by {@link PersistentState} plugin, after saving value under given key in browser local storage. This hook is fired when
* {@link Options#persistentState} option is enabled.
*
* @event Hooks#persistentStateSave
* @param {string} key Key.
* @param {Mixed} value Value to save.
*/
'persistentStateSave',
/**
* Fired by {@link ColumnSorting} and {@link MultiColumnSorting} plugins before sorting the column. If you return `false` value inside callback for hook, then sorting
* will be not applied by the Handsontable (useful for server-side sorting).
*
* This hook is fired when {@link Options#columnSorting} or {@link Options#multiColumnSorting} option is enabled.
*
* @event Hooks#beforeColumnSort
* @param {Array} currentSortConfig Current sort configuration (for all sorted columns).
* @param {Array} destinationSortConfigs Destination sort configuration (for all sorted columns).
* @returns {boolean | void} If `false` the column will not be sorted, `true` otherwise.
*/
'beforeColumnSort',
/**
* Fired by {@link ColumnSorting} and {@link MultiColumnSorting} plugins after sorting the column. This hook is fired when {@link Options#columnSorting}
* or {@link Options#multiColumnSorting} option is enabled.
*
* @event Hooks#afterColumnSort
* @param {Array} currentSortConfig Current sort configuration (for all sorted columns).
* @param {Array} destinationSortConfigs Destination sort configuration (for all sorted columns).
*/
'afterColumnSort',
/**
* Fired by {@link Autofill} plugin after setting range of autofill. This hook is fired when {@link Options#fillHandle}
* option is enabled.
*
* @event Hooks#modifyAutofillRange
* @param {Array} startArea Array of visual coordinates of the starting point for the drag-down operation (`[startRow, startColumn, endRow, endColumn]`).
* @param {Array} entireArea Array of visual coordinates of the entire area of the drag-down operation (`[startRow, startColumn, endRow, endColumn]`).
*/
'modifyAutofillRange',
/**
* Fired to allow modifying the copyable range with a callback function.
*
* @event Hooks#modifyCopyableRange
* @param {Array[]} copyableRanges Array of objects defining copyable cells.
*/
'modifyCopyableRange',
/**
* Fired by {@link CopyPaste} plugin before copying the values into clipboard and before clearing values of
* the selected cells. This hook is fired when {@link Options#copyPaste} option is enabled.
*
* @event Hooks#beforeCut
* @param {Array[]} data An array of arrays which contains data to cut.
* @param {object[]} coords An array of objects with ranges of the visual indexes (`startRow`, `startCol`, `endRow`, `endCol`)
* which will be cut out.
* @returns {*} If returns `false` then operation of the cutting out is canceled.
* @example
* ```js
* // To disregard a single row, remove it from the array using data.splice(i, 1).
* new Handsontable(element, {
* beforeCut: function(data, coords) {
* // data -> [[1, 2, 3], [4, 5, 6]]
* data.splice(0, 1);
* // data -> [[4, 5, 6]]
* // coords -> [{startRow: 0, startCol: 0, endRow: 1, endCol: 2}]
* }
* });
* // To cancel a cutting action, just return `false`.
* new Handsontable(element, {
* beforeCut: function(data, coords) {
* return false;
* }
* });
* ```
*/
'beforeCut',
/**
* Fired by {@link CopyPaste} plugin after data was cut out from the table. This hook is fired when
* {@link Options#copyPaste} option is enabled.
*
* @event Hooks#afterCut
* @param {Array[]} data An array of arrays which contains the cutted out data.
* @param {object[]} coords An array of objects with ranges of the visual indexes (`startRow`, `startCol`, `endRow`, `endCol`)
* which was cut out.
*/
'afterCut',
/**
* Fired before v