Updating Initial Adaptable State

Summary

AdapTable allow users to to ship design-time updates after go-live without wiping the rest of User State
This is done by using the numeric Revision property on a State section which replaces that entire section
Additionally a KeepUserDefined strategy re-applies Initial State items while keeping user-created ones

The concept behind Initial Adaptable State is that it provides - at design-time - the objects, entitlements and theme for initial use of the Application.

It is read once and merged into the user's Adaptable State, and then any run-time changes which users make will form part of their State and be continually updated.

But sometimes, after the application has gone live, developers might want to update one section in Initial Adaptable State while ensuring that the rest of the user's State remains untouched.

Revision Property

This can be accomplished through the Revision property in BaseState

Note

BaseState is the base interface for all User State sections

The Revision property is defined as follows:

Revision?: number | { Key: number; UpdateStrategy: 'Override' | 'KeepUserDefined' };

Replacing an Entire Section

As can be seen the Revision object can, in its simplified form, be a number.

In this scenario, if you increment (or provide from new) the revision number in a section of Initial State, AdapTable will replace that section (but only that section) in the user's State with the new InitialState.

Caution

Providing a number is replace only with no merging taking place

export default {
  CustomSort: {
    // This replaces existing Custom Sort section in User State with section provided here
    // (if the Revision Number - of 2 - is higher than the one currently in User State)
    // All other sections of Initial Adaptable State will remain untouched
    Revision: 2,
    CustomSorts: [
      {
        Name: 'CustomSort-Rating',
        ColumnId: 'Rating',
        SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
      },
    ],
  },
} as InitialState;

Revision — replace a whole section

Fork Fork

Starts with Format Column Revision 1 styling Name (blue)
Add User Format Column creates a runtime Format Column on Language (green)
Apply Revision 2 (Override) reloads with Initial State Format Column Revision 2 containing only Github Stars (yellow)
Because Revision is a number (Override), the whole Format Column section is replaced — the user Language style is removed
Other sections (e.g. Layout) are unchanged
Use Reset Demo to clear persisted state and start again

Try It Out

Confirm Name is blue
Click Add User Format Column — Language turns green
Click Apply Revision 2 (Override) — after reload, only Github Stars is styled (yellow); Name and user Language styles are gone
Click Reset Demo to restore Revision 1

import {
  AdaptableButton,
  AdaptableOptions,
  DashboardButtonContext,
  FormatColumn,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';
import {initialStateRevision1, initialStateRevision2} from './initialState';

const ADAPTABLE_STATE_KEY = 'docs/RevisionOverrideDemo';
const PHASE_STORAGE_KEY = `${ADAPTABLE_STATE_KEY}/phase`;

const userFormatColumn: FormatColumn = {
  Name: 'formatColumn-language-user',
  Scope: {
    ColumnIds: ['language'],
  },
  Style: {
    BackColor: '#32cd32',
    ForeColor: 'Black',
    FontWeight: 'Bold',
  },
};

function getPhase(): '1' | '2' {
  if (typeof localStorage === 'undefined') {
    return '1';
  }
  return localStorage.getItem(PHASE_STORAGE_KEY) === '2' ? '2' : '1';
}

const phase = getPhase();

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Revision Override Demo',
  adaptableStateKey: ADAPTABLE_STATE_KEY,
  initialState: phase === '2' ? initialStateRevision2 : initialStateRevision1,
  dashboardOptions: {
    customDashboardButtons: [
      {
        label: 'Add User Format Column',
        buttonStyle: {
          tone: 'neutral',
          variant: 'raised',
        },
        onClick: (
          _button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          const formatColumnApi = context.adaptableApi.formatColumnApi;
          if (formatColumnApi.getFormatColumnByName(userFormatColumn.Name)) {
            context.adaptableApi.systemStatusApi.setInfoSystemStatus(
              'User Format Column already present on Language'
            );
            return;
          }
          formatColumnApi.addFormatColumn(userFormatColumn);
          // TODO(adaptable-patch): remove after patch (Format Column refresh + UpdateStrategy KeepUserDefined)
          context.adaptableApi.gridApi.refreshColumns(['language']);
          context.adaptableApi.systemStatusApi.setInfoSystemStatus(
            'Added user Format Column on Language (green) — now Apply Revision 2'
          );
        },
      },
      {
        label: 'Apply Revision 2 (Override)',
        buttonStyle: {
          tone: 'info',
          variant: 'raised',
        },
        onClick: () => {
          localStorage.setItem(PHASE_STORAGE_KEY, '2');
          window.location.reload();
        },
      },
      {
        label: 'Reset Demo',
        buttonStyle: {
          tone: 'warning',
          variant: 'outlined',
        },
        onClick: () => {
          localStorage.removeItem(PHASE_STORAGE_KEY);
          localStorage.removeItem(ADAPTABLE_STATE_KEY);
          window.location.reload();
        },
      },
    ],
  },
};

Read-only

Loading demo…

Applying Initial State at Runtime

Besides a full wipe via StateApi.reloadInitialState, you can re-run the startup merge (Revision / Override / KeepUserDefined) without clearing user state:

StateApi.applyInitialState(newInitialState?) — merge Initial State into the current in-memory user state. When an argument is passed, AdaptableOptions.initialState is updated as well.
StateApi.remergePersistedState() — call StateOptions.loadState, then merge the result with the current Initial State (useful when persistence changed elsewhere).

Both persist afterward and refresh the grid / theme. Prefer these over remounting the grid when deploying section Revisions at runtime.

Updating Part of a Section

For a more granular approach you can provide an object which contains 2 properties:

Key of type number
UpdateStrategy which can have 2 values:
- Override - the newly provided Initial State will override whatever is stored in AdapTable State for that section (including items users created at run-time)
- KeepUserDefined - the newly provided Initial State replaces items that originally came from Initial State and keeps items users created at run-time.

Bump Key whenever you want to ship a new version of that section.

This is the usual way to re-apply design-time objects on top of already persisted state — for example change a Format Column background, or mark it IsReadOnly.

Re-include every Initial State item you still want (with the updated properties); omit one and it is dropped, even with KeepUserDefined.

export default {
  CustomSort: {
    // This adds a new item to the Custom Sort section of User State
    // The UpdateStrategy property is set to 'KeepUserDefined' (rather than 'Override')
    // so any user-created items in Custom Sort will not be replaced
    Revision: {Key: 5, UpdateStrategy: 'KeepUserDefined'},
    CustomSorts: [
      {
        Name: 'CustomSort-Rating',
        ColumnId: 'Rating',
        SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
      },
    ],
  },
} as InitialState;

Revision — KeepUserDefined

Fork Fork

Starts with Format Column Revision 1 styling Name (blue)
Add User Format Column creates a runtime Format Column on Language (green)
Apply Revision 2 (KeepUserDefined) reloads with Initial State Format Column Revision: { Key: 2, UpdateStrategy: 'KeepUserDefined' } containing only Github Stars (yellow)
New Initial State item (Github Stars) is applied; user-created Language style is kept; old Initial State Name style is replaced
Use Reset Demo to clear persisted state and start again

Try It Out

Confirm Name is blue
Click Add User Format Column — Language turns green
Click Apply Revision 2 (KeepUserDefined) — after reload, Github Stars is yellow and user Language remains green (Name blue is gone)
Click Reset Demo to restore Revision 1

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  FormatColumn,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';
import {initialStateRevision1, initialStateRevision2} from './initialState';

const ADAPTABLE_STATE_KEY = 'docs/RevisionKeepUserDefinedDemo';
const PHASE_STORAGE_KEY = `${ADAPTABLE_STATE_KEY}/phase`;

const userFormatColumn: FormatColumn = {
  Name: 'formatColumn-language-user',
  Scope: {
    ColumnIds: ['language'],
  },
  Style: {
    BackColor: '#32cd32',
    ForeColor: 'Black',
    FontWeight: 'Bold',
  },
};

function getPhase(): '1' | '2' {
  if (typeof localStorage === 'undefined') {
    return '1';
  }
  return localStorage.getItem(PHASE_STORAGE_KEY) === '2' ? '2' : '1';
}

const phase = getPhase();

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Revision KeepUserDefined Demo',
  adaptableStateKey: ADAPTABLE_STATE_KEY,
  initialState: phase === '2' ? initialStateRevision2 : initialStateRevision1,
  dashboardOptions: {
    customToolbars: [
      {
        name: 'RevisionDemo',
        title: 'Revision',
        toolbarButtons: [
          {
            label: 'Add User Format Column',
            buttonStyle: {
              tone: 'neutral',
              variant: 'raised',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const formatColumnApi = context.adaptableApi.formatColumnApi;
              if (formatColumnApi.getFormatColumnByName(userFormatColumn.Name)) {
                context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                  'User Format Column already present on Language'
                );
                return;
              }
              formatColumnApi.addFormatColumn(userFormatColumn);
              // TODO(adaptable-patch): remove after patch (Format Column refresh + UpdateStrategy KeepUserDefined)
              context.adaptableApi.gridApi.refreshColumns(['language']);
              context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                'Added user Format Column on Language (green) — now Apply Revision 2'
              );
            },
          },
          {
            label: 'Apply Revision 2 (KeepUserDefined)',
            buttonStyle: {
              tone: 'info',
              variant: 'raised',
            },
            onClick: () => {
              localStorage.setItem(PHASE_STORAGE_KEY, '2');
              window.location.reload();
            },
          },
          {
            label: 'Reset Demo',
            buttonStyle: {
              tone: 'warning',
              variant: 'outlined',
            },
            onClick: () => {
              localStorage.removeItem(PHASE_STORAGE_KEY);
              localStorage.removeItem(ADAPTABLE_STATE_KEY);
              window.location.reload();
            },
          },
        ],
      },
    ],
  },
};

Read-only

Loading demo…

FAQ

When should I use a number vs { Key, UpdateStrategy }? Use a plain number when you want to replace the whole section (same as UpdateStrategy: 'Override'). Use the object form with KeepUserDefined when users may have created their own items in that section and you only want to refresh the design-time ones.

Does bumping Revision wipe other Modules' State? No, Revision is per section (e.g. Format Column, Custom Sort). Only the section whose Revision increases is merged; every other section of User State is left alone.

With KeepUserDefined, what happens to an Initial State item I omit? It is dropped. Re-include every design-time item you still want (with any updated properties). User-created items are kept; old Initial State items that you no longer ship are not.

Do I need to remount the grid to apply a new Revision? Usually no - instead use one of 3 State API funcions:

applyInitialState (merge into current in-memory state) or
remergePersistedState (reload persisted state, then merge)
reloadInitialState - to use only when you intentionally want a full wipe back to Initial State

What if the new Revision Key is not higher than the stored one? AdapTable ignores the update for that section. Bump Key (or the numeric Revision) whenever you ship a new version of the Initial State for that section.

PreviousPersisting AdapTable State NextManaging AdapTable State