This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# 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.

# Methods

# createAndRegisterIndexMap

Source code (opens new window)

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

Creates and register the new IndexMap for specified IndexMapper instance.

Param Type Description
indexName string The uniq index name.
mapType string The index map type (e.q. "hiding, "trimming", "physicalIndexToValue").
[initValueOrFn] * optional The initial value for the index map.

# createChangesObserver

Source code (opens new window)

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.

# fitToLength

Source code (opens new window)

indexMapper.fitToLength(length)

Trim/extend the mappers to fit the desired length.

Param Type Description
length number New mapper length.

# getFirstNotHiddenIndex

Source code (opens new window)

indexMapper.getFirstNotHiddenIndex(fromVisualIndex, incrementBy, searchAlsoOtherWayAround, indexForNextSearch) ⇒ number | null

Search for the first visible, not hidden index (represented by a visual index).

Param Type Default Description
fromVisualIndex number Visual start index. Starting point for finding destination index. Start point may be destination point when handled index is NOT hidden.
incrementBy number We are searching for a next visible indexes by increasing (to be precise, or decreasing) indexes. This variable represent indexes shift. We are looking for an index: - for rows: from the left to the right (increasing indexes, then variable should have value 1) or other way around (decreasing indexes, then variable should have the value -1) - for columns: from the top to the bottom (increasing indexes, then variable should have value 1) or other way around (decreasing indexes, then variable should have the value -1).
searchAlsoOtherWayAround boolean false The argument determine if an additional other way around search should be performed, when the search in the first direction had no effect in finding visual index.
indexForNextSearch number Visual index for next search, when the flag is truthy.

Returns: number | null - Visual column index or null.

# getIndexesSequence

Source code (opens new window)

indexMapper.getIndexesSequence() ⇒ Array

Get sequence of indexes.

Returns: Array - Physical indexes.

# getNotHiddenIndexes

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

indexMapper.getNumberOfIndexes() ⇒ number

Get number of all indexes.

# getPhysicalFromRenderableIndex

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

indexMapper.getRenderableIndexesLength() ⇒ number

Get length of all NOT trimmed and NOT hidden indexes.

# getVisualFromPhysicalIndex

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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.

# registerMap

Source code (opens new window)

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 (opens new window)

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 (opens new window)

indexMapper.setIndexesSequence(indexes)

Set completely new indexes sequence.

Param Type Description
indexes Array Physical indexes.

# suspendOperations

Source code (opens new window)

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 (opens new window)

indexMapper.unregisterAll()

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

# unregisterMap

Source code (opens new window)

indexMapper.unregisterMap(name)

Unregister a map with given name.

Param Type Description
name string Name of the index map.
Last Updated: Apr 12, 2024