Store & State

DataGridXL has its own virtual DOM implementation. Trust us, that sounds more complicated than it really is.

How DataGridXL uses stores

When you initially pass data to your grid, 3 stores are automatically created: _rowStore, _colStore and _cellStore.

When you create a 3×3 grid, you'll have 3 items in your rowStore, 3 items in your colStore and 9 items in the grid's cellStore.

Each row and each column is given an id, much like a database id in SQL database tables. This way, the stores rows and columns are de-coupled from their positions in the grid document.

0
1
2
1
2
3
0
1
2
1
2
3
{x:0,y:0}
(1,1)
{x:0,y:1}
(2,1)
{x:0,y:2}
(3,1)
{x:1,y:0}
(1,2)
{x:1,y:1}
(2,2)
{x:1,y:2}
(3,2)
{x:2,y:0}
(1,3)
{x:2,y:1}
(2,3)
{x:2,y:2}
(3,3)

The illustration above demonstrates this 3×3 grid (without headers). The numbers in grey represent the document's row and column coordinates (also named rowCoord & colCoord). The yellow numbers represent the row and column IDs that happen to take that spot.

Each illustrated cell displays their cell coordinates (formatted as {x:colCoord,y:rowCoord}) and their corresponding rowId & colId values (in yellow).

Changing the value of cell {x:0,y:2} will change the cell value of the cell at getCellFromStore(3,1), since the cell is really at the intersection of rowId 3 and colId 1.

DataGridXL state management

The order of rows and columns in the data grid document are stored in _rowList and _colList resp. These lists are nothing more than arrays of ids. If you'd console.log(grid._colList) or grid._rowList you'll see that they both have values [1,2,3]. (The yellow numbers in the illustration represent these lists.)

Moving a column

When your user moves a column (or when a column is moved using the grid.moveCols() method), there is no messing around with DOM nodes. DataGridXL looks at _colList, shuffles the column order, then redraws the grid.

The below illustration demonstrates the new order of IDs after a user would move the last column to the first spot:

0
1
2
3
1
2
0
1
2
1
2
3
{x:0,y:0}
(1,3)
{x:0,y:1}
(2,3)
{x:0,y:2}
(3,3)
{x:1,y:0}
(1,1)
{x:1,y:1}
(2,1)
{x:1,y:2}
(3,1)
{x:2,y:0}
(1,2)
{x:2,y:1}
(2,2)
{x:2,y:2}
(3,2)

You'll notice that the cellCoords (and rowCoords and colCoords) remain the same. It's only the underlying IDs that have changed.

It is a fool-proof way to implement actions like move, insert and delete, knowing that there will never be unwanted DOM surprises.

Useful methods

getColFromStore(colId) takes a column ID and returns a column object. A column object holds properties like title, field, align, width, node and more.

getRowFromStore(rowId) takes a row ID and returns a row object. A row object only holds it own id and a title property. A row is untitled by default.

getCellFromStore(rowId, colId) needs both a row ID and a col ID. This is the "address" of a cell. The cell object holds a value property.

To get the coordinate (index) of a column by ID, use grid._colList.indexOf(colId). To do a "reverse lookup" and get the ID of a column by index (colCoord), use grid._colList[colCoord].


Leave email to receive latest updates!