feat(ngrid): support state serialization / deserialization

[Shlomi Assaf]

This is the main ticket for state serialization / deserialization:

• Support tagging tables with unique id's
• Support serialization of the state
• Support deserialization of the state from a serialized source
• Support save / load abstraction using an async interface
• Support save / load implementation from the local storage
• Support developer-defined API to disable serialization of specific domains / properties

The goal is to be able to save state describing the grid and load that data on-demand.

Why

The are 2 main use cases to save the state:

1. Persisting user changes between sessions
2. Granular grid definitions

The 1st use case is straight forward, a user might change the look and/or behaviour of the grid and would like to persist this change across sessions ( (e.g. column hiding, reordering, resizing, etc...).

The 2nd use case is to allow the developer to cascade the grid's definitions and compose the final state from one or multiple states. For example, having a global state that will be used on all grids upon load, then adding more layers based on group, page or whatever.

This will reduce a lot of boilerplate and code required to define grid properties, column definitions and more.

To support the 2nd use-case the restoring process should support 2 modes:

• Overwrite: Restoring state even if it exists
• Merge: Restoring state only if it does not exist

In addition, the developer should be able to, for each save / restore, specify points in the state to ignore. For example, never persist the showHeader state.
This is also important for support of the combination between the 1st and 2nd use cases. For example, using the 2nd use-case to restore identityProp but ignoring it in the 1st use-case.

Source & State

The state is build from multiple mini-state chunks that come from different sources so the API should support external input.

State must be serializable, i.e. everything JSON, no functions, classes etc...

A state source should be the smallest logical unit of the domain it holds the state for. A guideline for a source might be an instance that only save primitive it holds.

For example, the grid is a source but each column instance on it is a source. The grid will save state for primitive properties and each columns instance will save state for it's own properties.

Currently known state sources:

• The grid instance (hideColumns, showFooter, showHeader, etc..)
• Current column definition set (PblColumn instances)
• Plugins

There is no definition for what a state is but a guideline might be everything that the user can change and we can deterministically point to when restoring..

For example, we know that the grid will not change so its easy to save/restore things like hideColumns, showFooter, showHeader etc..

We also know that each cell has a context which is pure state but we can't point to it when restoring because the dataset might be different when we restore so cell / row context is not serializable.

On the other hand, there are vague cases, such as columns...
We know that a column exists between restores but we must ensure the source grid of the restore (i.e. uniquely identifying the origin grid) and more over, we need to take into account non-api changes like column removal / addition etc...

We ignore persisting between code changes that might introduce API changes, this is a migration issue and should be supported in a different story.

State mapping

Grid

• showHeader
• showFooter
• focusMode
• identityProp
• usePagination
• hideColumns
• fallbackMinHeight

Columns

The state of all columns is save as 1 object that should reflect the structure of PblNgridColumnDefinitionSet so it could be passed on to the column factory (PblColumnFactory).

This includes properties from PblMetaRowDefinitions and PblColumnSet.

In addition, each column type should be handled by a specific logical serializer.

• PblBaseColumnDefinition

  • id, label, css
  • type ¹
  • widths ^{2 3}
  • data ¹

• PblMetaColumnDefinition & PblColumnGroupDefinition

  • All data

• PblColumnDefinition

  • prop (take from orgProp if instance)
  • headerType ¹
  • footerType ¹
  • sort ⁴
  • sortAlias

[ 1 ]: Object with potentially unserialized content.
[ 2 ]: Widths include width, minWidth, maxWidth
[ 3 ]: Widths are constantly updated by the grid, the serialized values should only be those set by the user and not by the resizing logic.
[ 4 ]: Only if boolean, otherwise unserializable

[Shlomi Assaf]

Currently not implemented:

• Overwrite / Merge modes... its overwrite only.