Providing Initial Adaptable State

Developers will populate each new AdapTable instance with initial Adaptable State.

This means that when end-users open the new application for the first time, they won't just seen a clean AG Grid instance but, rather, one pre-loaded with multiple Layouts, Searches, Styles, Edit Rules, Reports etc.

This enables a grid to be provided that matches users needs, allowing them to be productive immediately.

The Initial State is then merged into Adaptable State and can be added or edited (if the user's Entitlements allow) and persisted (either locally or remotely) using AdapTable's State Management.

The Basics

Initial State is a JSON object created at design-time.

It consists of a series of (nullable) properties that themselves each implement the BaseState class.

Most of the contents of each section are collections of Adaptable Objects (e.g. Layouts) but can also be string properties (e.g name of the Current Layout).

It is provided to AdapTable via the initialState property in the base section of Adaptable Options.

How It Works

When AdapTable is first loaded, the Initial Adaptable State is read into memory and then stored.

During that initial session AdapTable will merge the Initial Adaptable State with any user state that was created.

Subsequently, each time the application is launched, that User State is retrieved and the particular AdapTable instance is pre-populated with it.

Updating Initial Adaptable State

As the name implies, 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

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.

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 Stateg will remain untouched
    Revision: 2,
    CustomSorts: [
      {
        Name: 'CustomSort-Rating',
        ColumnId: 'Rating',
        SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
      },
    ],
  },
} as InitialState;

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 provided Initial State will override whatever is stored in AdapTable State for that section
  • KeepUserDefined - the provided Initial State will be added to what is stored in Adaptable State

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;

Providing Custom Data

The Application State section of Adaptable State contains an ApplicationDataEntries array.

This is essentially a set of key / value pairs that you can populate with any data that you want and which AdapTable will store in its state.

Adaptable Objects

All objects in Initial Adaptable State inherit from AdaptableObject.

Adaptable Object Properties

The AdaptableObject is defined as follows:

Uuid

The Uuid property is of type TypeUuid and used for easy identification of objects.

It allows AdapTable instances to share state and inform each other of CRUD events on an item.

IsReadOnly

Entitlements in AdapTable typically operate at the Module level.

However, sometimes a use case demands that while the Module has a 'Full' entitlement (i.e. it is editable), one particular object must be ReadOnly (i.e. cannot be deleted).

This property is designed for precisely this reason, and it will overrride the 'Full' Entitlement in the Module.

Source

The Source property is applied by AdapTable and defines where the object was first created.

AdapTable will dynamically set this property to be one of 2 values:

• InitialState - the object was initially provided in Initial Adaptable State
• User - the object was created by the user at run-time in the AdapTable UI

Object Tags

Every Adaptable Object has a Tags property (of type AdaptableObjectTag).

A Tag is a very simple object that just contains a string value.

However it allows you to provide additional information to any object that you create.

Object Meta Data

Every Adaptable Object has a MetaData property.

This is designed to allow developers to assign custom properties / data to the object.

AdaptableVersion

Every Adaptable Object states which version of AdapTable is being run.

This is useful if you have multiple applications running, using different AdapTable versions.

Suspending Objects

To DO - go to link