IndexMapper

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, HidingMap, and TrimmingMap.

Classes

IndexMapper

Methods

createAndRegisterIndexMap(indexName, mapType, initValueOrFn){IndexMap}

Creates and register the new IndexMap for specified IndexMapper instance.

Parameters:
Name 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.

Returns: {IndexMap}

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.

Parameters:
Name Type Description
indexMapType string

The index map type which we want to observe.
Currently, only the 'hiding' index map types are observable.

Returns: {ChangesObserver}

getFirstNotHiddenIndex(fromVisualIndex, incrementBy, searchAlsoOtherWayAround, indexForNextSearch){number|null}

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

Parameters:
Name 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(){Array}

Get sequence of indexes.

Returns: {Array} Physical indexes.

getNotHiddenIndexes(readFromCache){Array}

Get all NOT hidden indexes.

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

Parameters:
Name 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(){number}

Get length of all NOT hidden indexes.

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

Returns: {number}

getNotTrimmedIndexes(readFromCache){Array}

Get all NOT trimmed indexes.

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

Parameters:
Name 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(){number}

Get length of all NOT trimmed indexes.

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

Returns: {number}

getNumberOfIndexes(){number}

Get number of all indexes.

Returns: {number}

getPhysicalFromRenderableIndex(renderableIndex){null|number}

Get a physical index corresponding to the given renderable index.

Parameters:
Name Type Description
renderableIndex number

Renderable index.

Returns: {null|number}

getPhysicalFromVisualIndex(visualIndex){number|null}

Get a physical index corresponding to the given visual index.

Parameters:
Name Type Description
visualIndex number

Visual index.

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

getRenderableFromVisualIndex(visualIndex){null|number}

Get a renderable index corresponding to the given visual index.

Parameters:
Name Type Description
visualIndex number

Visual index.

Returns: {null|number}

getRenderableIndexes(readFromCache){Array}

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

Parameters:
Name 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(){number}

Get length of all NOT trimmed and NOT hidden indexes.

Returns: {number}

getVisualFromPhysicalIndex(physicalIndex){number|null}

Get a visual index corresponding to the given physical index.

Parameters:
Name Type Description
physicalIndex number

Physical index to search.

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

getVisualFromRenderableIndex(renderableIndex){null|number}

Get a visual index corresponding to the given renderable index.

Parameters:
Name Type Description
renderableIndex number

Renderable index.

Returns: {null|number}

initToLength(length)

Set default values for all indexes in registered index maps.

Parameters:
Name Type Description
length number optional

Destination length for all stored index maps.

isHidden(physicalIndex){boolean}

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

Parameters:
Name Type Description
physicalIndex number

Physical index.

Returns: {boolean}

isTrimmed(physicalIndex){boolean}

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

Parameters:
Name Type Description
physicalIndex number

Physical index.

Returns: {boolean}

moveIndexes(movedIndexes, finalIndex)

Move indexes in the index mapper.

Parameters:
Name Type Description
movedIndexes number | Array

Visual index(es) to move.

finalIndex number

Visual index being a start index for the moved elements.

registerMap(uniqueName, indexMap){IndexMap}

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

Parameters:
Name Type Description
uniqueName string

Name of the index map. It should be unique.

indexMap IndexMap

Registered index map updated on items removal and insertion.

Returns: {IndexMap}

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(indexes)

Set completely new indexes sequence.

Parameters:
Name Type Description
indexes Array

Physical indexes.

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()

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

unregisterMap(name)

Unregister a map with given name.

Parameters:
Name Type Description
name string

Name of the index map.

Class: IndexMapper