IndexMapper

Plugin: IndexMapper

Description

Index mapper stores, registers and manages the indexes on the basis of calculations collected from the subsidiary maps. It should be seen as a single source of truth (regarding row and column indexes, for example, their sequence, information if they are skipped in the process of rendering (hidden or trimmed), values linked to them) for any operation that considers CRUD actions such as insertion, movement, removal etc, and is used to properly calculate physical and visual indexes translations in both ways. It has a built-in cache that is updated only when the data or structure changes.

Physical index is a type of an index from the sequence of indexes assigned to the data source rows or columns (from 0 to n, where n is number of the cells on the axis of data set). Visual index is a type of an index from the sequence of indexes assigned to rows or columns existing in DataMap (from 0 to n, where n is number of the cells on the axis of data set). Renderable index is a type of an index from the sequence of indexes assigned to rows or columns whose may be rendered (when they are in a viewport; from 0 to n, where n is number of the cells renderable on the axis).

There are different kinds of index maps which may be registered in the collections and can be used by a reference. They also expose public API and trigger two local hooks such as init (on initialization) and change (on change).

These are: IndexesSequence, PhysicalIndexToValueMap, LinkedPhysicalIndexToValueMap, HidingMap, and TrimmingMap.

Members

indexesChangeSource

Source code

indexMapper.indexesChangeSource : undefined | string

Flag informing about source of the change.

Methods

createAndRegisterIndexMap

Source code

indexMapper.createAndRegisterIndexMap(indexName, mapType, [initValueOrFn]) ⇒ IndexMap

Creates and registers a new IndexMap for a specified IndexMapper instance.

Param	Type	Description
indexName	string	A unique index name.
mapType	string	The index map type (e.g., “hiding”, “trimming”, “physicalIndexToValue”).
[initValueOrFn]	*	optional The initial value for the index map.

createChangesObserver

Source code

indexMapper.createChangesObserver(indexMapType) ⇒ ChangesObserver

It creates and returns the new instance of the ChangesObserver object. The object allows listening to the index changes that happen while the Handsontable is running.

Param	Type	Description
indexMapType	string	The index map type which we want to observe. Currently, only the ‘hiding’ index map types are observable.

destroy

Source code

indexMapper.destroy()

Destroys the IndexMapper instance. Clears all registered map observers and unregisters all maps from all collections.

fitToLength

Source code

indexMapper.fitToLength(length)

Trim/extend the mappers to fit the desired length.

Param	Type	Description
length	number	New mapper length.

getIndexesSequence

Source code

indexMapper.getIndexesSequence() ⇒ Array

Get sequence of indexes.

Returns: Array - Physical indexes.

getNearestNotHiddenIndex

Source code

indexMapper.getNearestNotHiddenIndex(fromVisualIndex, searchDirection, searchAlsoOtherWayAround) ⇒ number | null

Search for the nearest not-hidden row or column.

Param	Type	Default	Description
fromVisualIndex	number		The visual index of the row or column from which the search starts. If the row or column from which the search starts is not hidden, the method simply returns the fromVisualIndex number.
searchDirection	number		The search direction. 1: search from fromVisualIndex to the end of the dataset. -1: search from fromVisualIndex to the beginning of the dataset (i.e., to the row or column at visual index 0).
searchAlsoOtherWayAround	boolean	false	true: if a search in a first direction failed, try the opposite direction. false: search in one direction only.

Returns: number | null - A visual index of a row or column, or null.

getNotHiddenIndexes

Source code

indexMapper.getNotHiddenIndexes([readFromCache]) ⇒ Array

Get all NOT hidden indexes.

Note: Indexes marked as hidden are included in a DataMap, but aren’t rendered.

Param	Type	Default	Description
[readFromCache]	boolean	true	optional Determine if read indexes from cache.

Returns: Array - List of physical indexes. Please keep in mind that index of this native array IS NOT a “visual index”.

getNotHiddenIndexesLength

Source code

indexMapper.getNotHiddenIndexesLength() ⇒ number

Get length of all NOT hidden indexes.

Note: Indexes marked as hidden are included in a DataMap, but aren’t rendered.

getNotTrimmedIndexes

Source code

indexMapper.getNotTrimmedIndexes([readFromCache]) ⇒ Array

Get all NOT trimmed indexes.

Note: Indexes marked as trimmed aren’t included in a DataMap and aren’t rendered.

Param	Type	Default	Description
[readFromCache]	boolean	true	optional Determine if read indexes from cache.

Returns: Array - List of physical indexes. Index of this native array is a “visual index”, value of this native array is a “physical index”.

getNotTrimmedIndexesLength

Source code

indexMapper.getNotTrimmedIndexesLength() ⇒ number

Get length of all NOT trimmed indexes.

Note: Indexes marked as trimmed aren’t included in a DataMap and aren’t rendered.

getNumberOfIndexes

Source code

indexMapper.getNumberOfIndexes() ⇒ number

Get number of all indexes.

getPhysicalFromRenderableIndex

Source code

indexMapper.getPhysicalFromRenderableIndex(renderableIndex) ⇒ null | number

Get a physical index corresponding to the given renderable index.

Param	Type	Description
renderableIndex	number	Renderable index.

getPhysicalFromVisualIndex

Source code

indexMapper.getPhysicalFromVisualIndex(visualIndex) ⇒ number | null

Get a physical index corresponding to the given visual index.

Param	Type	Description
visualIndex	number	Visual index.

Returns: number | null - Returns translated index mapped by passed visual index.

getRenderableFromVisualIndex

Source code

indexMapper.getRenderableFromVisualIndex(visualIndex) ⇒ null | number

Get a renderable index corresponding to the given visual index.

Param	Type	Description
visualIndex	number	Visual index.

getRenderableIndexes

Source code

indexMapper.getRenderableIndexes([readFromCache]) ⇒ Array

Get list of physical indexes (respecting the sequence of indexes) which may be rendered (when they are in a viewport).

Param	Type	Default	Description
[readFromCache]	boolean	true	optional Determine if read indexes from cache.

Returns: Array - List of physical indexes. Index of this native array is a “renderable index”, value of this native array is a “physical index”.

getRenderableIndexesLength

Source code

indexMapper.getRenderableIndexesLength() ⇒ number

Get length of all NOT trimmed and NOT hidden indexes.

getVisualFromPhysicalIndex

Source code

indexMapper.getVisualFromPhysicalIndex(physicalIndex) ⇒ number | null

Get a visual index corresponding to the given physical index.

Param	Type	Description
physicalIndex	number	Physical index to search.

Returns: number | null - Returns a visual index of the index mapper.

getVisualFromRenderableIndex

Source code

indexMapper.getVisualFromRenderableIndex(renderableIndex) ⇒ null | number

Get a visual index corresponding to the given renderable index.

Param	Type	Description
renderableIndex	number	Renderable index.

initToLength

Source code

indexMapper.initToLength([length])

Set default values for all indexes in registered index maps.

Param	Type	Description
[length]	number	optional Destination length for all stored index maps.

isHidden

Source code

indexMapper.isHidden(physicalIndex) ⇒ boolean

Get whether index is hidden. Index marked as hidden is included in a DataMap, but isn’t rendered.

Param	Type	Description
physicalIndex	number	Physical index.

isTrimmed

Source code

indexMapper.isTrimmed(physicalIndex) ⇒ boolean

Get whether index is trimmed. Index marked as trimmed isn’t included in a DataMap and isn’t rendered.

Param	Type	Description
physicalIndex	number	Physical index.

moveIndexes

Source code

indexMapper.moveIndexes(movedIndexes, finalIndex)

Move indexes in the index mapper.

Param	Type	Description
movedIndexes	number Array	Visual index(es) to move.
finalIndex	number	Visual index being a start index for the moved elements.

observeMapChange

Source code

indexMapper.observeMapChange(map, callback) ⇒ function

Registers an observer for batched changes on a specific index map. During batched operations (IndexMapper#suspendOperations/IndexMapper#resumeOperations), changes are coalesced and the callback fires once when the batch completes. Outside of batching, the callback fires immediately on each change.

Works with maps registered in the various maps collection.

Param	Type	Description
map	IndexMap	The map instance to observe.
callback	function	Called when the observed map’s values change (coalesced during batches).

Returns: function - Disposer function that removes the observer.

registerMap

Source code

indexMapper.registerMap(uniqueName, indexMap) ⇒ IndexMap

Register map which provide some index mappings. Type of map determining to which collection it will be added.

Param	Type	Description
uniqueName	string	Name of the index map. It should be unique.
indexMap	IndexMap	Registered index map updated on items removal and insertion.

resumeOperations

Source code

indexMapper.resumeOperations()

Resumes the cache update for this map. It recalculates the cache and restores the default behavior where each map modification updates the cache.

setIndexesSequence

Source code

indexMapper.setIndexesSequence(indexes)

Set completely new indexes sequence.

Param	Type	Description
indexes	Array	Physical indexes.

suspendOperations

Source code

indexMapper.suspendOperations()

Suspends the cache update for this map. The method is helpful to group multiple operations, which affects the cache. In this case, the cache will be updated once after calling the resumeOperations method.

unregisterAll

Source code

indexMapper.unregisterAll()

Unregisters all collected index map instances from all map collection types.

unregisterMap

Source code

indexMapper.unregisterMap(name)

Unregister a map with given name.

Param	Type	Description
name	string	Name of the index map.