JavaScript Data Grid IndexMapper
- Description
- Methods
- createAndRegisterIndexMap
- createChangesObserver
- fitToLength
- getFirstNotHiddenIndex
- getIndexesSequence
- getNearestNotHiddenIndex
- getNotHiddenIndexes
- getNotHiddenIndexesLength
- getNotTrimmedIndexes
- getNotTrimmedIndexesLength
- getNumberOfIndexes
- getPhysicalFromRenderableIndex
- getPhysicalFromVisualIndex
- getRenderableFromVisualIndex
- getRenderableIndexes
- getRenderableIndexesLength
- getVisualFromPhysicalIndex
- getVisualFromRenderableIndex
- initToLength
- isHidden
- isTrimmed
- moveIndexes
- registerMap
- resumeOperations
- setIndexesSequence
- suspendOperations
- unregisterAll
- unregisterMap
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
Deprecated
Search for the first visible, not hidden index (represented by a visual index).
This method is deprecated and will be removed in a next major version of Handsontable. Use the IndexMapper#getNearestNotHiddenIndex method instead.
| 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 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) - for columns: 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). | |
| 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.
getNearestNotHiddenIndex
Source code (opens new window)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 (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. |