# Providing Initial Adaptable State

Canonical page: https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state

- AdapTable instances are pre-populated at Design Time with Initial Adaptable State
- These are the objects that Users require for first time use
- `Layout` section is required and must contain at least one Layout, (unless [Default Layouts](https://www.adaptabletools.com/docs/handbook-layouts-default/index.md) are configured)
- When Adaptable loads, the Initial State is saved into [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md)
- The contents of this Initial State is arranged by Module and consist of both:
  - individual properties
  - collections of AdapTable Objects

See the list of Initial State sections in [Initial Adaptable State Reference](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md)

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 see a clean AG Grid instance but, rather, one pre-loaded with multiple Layouts, Searches, Styles, Edit Rules, Reports etc.

- Initial State constitutes those objects which can (and will) be **overridden** at run-time and saved by user's actions
- Anything which **cannot** be changed at run-time is provided through [Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md)

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](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md) and can be added or edited (if the user's [Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md) allow) and persisted (either locally or remotely).

- As the name implies Initial State should **only** be used for **first-time** use of the Application
- AdapTable State should be relied on to manage all subsequent state-related behaviour

## The Basics

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

It consists of a series of properties that themselves each implement the [`BaseState`](https://www.adaptabletools.com/docs/reference/basestate.md) class.

Every section is optional.

The exception is the `Layout` section which is required and contain at least one Layout, (unless using [Default Layouts](https://www.adaptabletools.com/docs/handbook-layouts-default/index.md))

Most of the contents of each section are collections of Adaptable Objects (e.g. [Layouts](https://www.adaptabletools.com/docs/handbook-layouts/index.md)) 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](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md).

### `initialState`

Initial Adaptable Objects provided in an Adaptable Instance

  [`InitialState`](https://www.adaptabletools.com/docs/reference/initialstate.md)

Initial State is the Adaptable State provided at design time for **first-time** use.

The full definition of the object is as follows:

| Property | Type | Description |
| --- | --- | --- |
| [Alert](https://www.adaptabletools.com/docs/reference/initialstate.md#alert) | [`AlertState`](https://www.adaptabletools.com/docs/reference/alertstate.md) | Collection of `AlertDefinitions` which will fire Alerts when the rule is met |
| [Application](https://www.adaptabletools.com/docs/reference/initialstate.md#application) | [`ApplicationState`](https://www.adaptabletools.com/docs/reference/applicationstate.md) | Empty state section (only populated at Design Time) available for User to store their own data with the rest of AdapTable state. |
| [CalculatedColumn](https://www.adaptabletools.com/docs/reference/initialstate.md#calculatedcolumn) | [`CalculatedColumnState`](https://www.adaptabletools.com/docs/reference/calculatedcolumnstate.md) | Collection of *CalculatedColumn* objects that will display a value based on other cells in the row (using a Calculated Column Expression) |
| [Charting](https://www.adaptabletools.com/docs/reference/initialstate.md#charting) | [`ChartingState`](https://www.adaptabletools.com/docs/reference/chartingstate.md) | Saved charts. AG Grid charts are `ChartDefinitions` (`Name` and `Model`). Application charts are `ExternalChartDefinitions` (`Name` and `Data`). |
| [CustomSort](https://www.adaptabletools.com/docs/reference/initialstate.md#customsort) | [`CustomSortState`](https://www.adaptabletools.com/docs/reference/customsortstate.md) | Collection of *Custom Sort* objects to allow some columns to be sorted in non-standard (e.g. non alphabetical) ways |
| [Dashboard](https://www.adaptabletools.com/docs/reference/initialstate.md#dashboard) | [`DashboardState`](https://www.adaptabletools.com/docs/reference/dashboardstate.md) | Large series of properties to give users full control over the look and feel of the *Dashboard* - the section above the grid with toolbars and buttons |
| [Export](https://www.adaptabletools.com/docs/reference/initialstate.md#export) | [`ExportState`](https://www.adaptabletools.com/docs/reference/exportstate.md) | Collection of *Report* objects, together with name of the Current Report, as part of AdapTable export Module |
| [FlashingCell](https://www.adaptabletools.com/docs/reference/initialstate.md#flashingcell) | [`FlashingCellState`](https://www.adaptabletools.com/docs/reference/flashingcellstate.md) | Flashing Cell definitions. Each one names a column scope and a boolean rule, and flashes a cell, a row, or an aggregated cell. |
| [FormatColumn](https://www.adaptabletools.com/docs/reference/initialstate.md#formatcolumn) | [`FormatColumnState`](https://www.adaptabletools.com/docs/reference/formatcolumnstate.md) | Format Columns. Each one colours cells, changes how values are displayed, or both, for a column scope. Omit `Rule` to apply it on every row. |
| [FreeTextColumn](https://www.adaptabletools.com/docs/reference/initialstate.md#freetextcolumn) | [`FreeTextColumnState`](https://www.adaptabletools.com/docs/reference/freetextcolumnstate.md) | Collection of *FreeText* objects that define user-owned columns whose cell values are stored in Adaptable State (not the grid DataSource). Use for editable per-row fields such as ops notes, flags, or codes — distinct from cell-level Notes and Comments. |
| [Layout](https://www.adaptabletools.com/docs/reference/initialstate.md#layout) | [`LayoutState`](https://www.adaptabletools.com/docs/reference/layoutstate.md) | Collection of *Layouts* to name (and manage) sets of column visibility, order, grouping, sorts, aggregations, filters etc.<br/>Required unless `layoutOptions.autoCreateLayout` is set. |
| [NamedQuery](https://www.adaptabletools.com/docs/reference/initialstate.md#namedquery) | [`NamedQueryState`](https://www.adaptabletools.com/docs/reference/namedquerystate.md) | Named Queries other expressions can call with `QUERY('Name')`. A boolean query can be a Grid Filter or an Alert rule. |
| [Note](https://www.adaptabletools.com/docs/reference/initialstate.md#note) | [`NoteState`](https://www.adaptabletools.com/docs/reference/notestate.md) | Notes. One piece of text on one cell, located by primary key and column id. |
| [PlusMinus](https://www.adaptabletools.com/docs/reference/initialstate.md#plusminus) | [`PlusMinusState`](https://www.adaptabletools.com/docs/reference/plusminusstate.md) | Plus Minus module: nudge rules. Optional `IncrementKey` / `DecrementKey` on each nudge<br/>accept either a single key or a keyboard shortcut combination (e.g. `shift+Enter`); when<br/>omitted, `AdaptableOptions.plusMinusOptions` applies, then `+` / `-`. |
| [QuickSearch](https://www.adaptabletools.com/docs/reference/initialstate.md#quicksearch) | [`QuickSearchState`](https://www.adaptabletools.com/docs/reference/quicksearchstate.md) | Quick Search text restored at startup, and the styles used to highlight matches. |
| [Shortcut](https://www.adaptabletools.com/docs/reference/initialstate.md#shortcut) | [`ShortcutState`](https://www.adaptabletools.com/docs/reference/shortcutstate.md) | Collection of *Shortcut* objects to aid data entry and prevent &#39;fat finger&#39; issues |
| [StatusBar](https://www.adaptabletools.com/docs/reference/initialstate.md#statusbar) | [`StatusBarState`](https://www.adaptabletools.com/docs/reference/statusbarstate.md) | Status bars. Each `Key` matches an AG Grid `statusPanels` entry whose component is `AdaptableStatusPanel`. |
| [StyledColumn](https://www.adaptabletools.com/docs/reference/initialstate.md#styledcolumn) | [`StyledColumnState`](https://www.adaptabletools.com/docs/reference/styledcolumnstate.md) | Styled Columns. Each entry draws one column with a single visual style. |
| [Theme](https://www.adaptabletools.com/docs/reference/initialstate.md#theme) | [`ThemeState`](https://www.adaptabletools.com/docs/reference/themestate.md) | Active theme (`light`, `dark` or `os`) and which shipped themes are offered. |
| [ToolPanel](https://www.adaptabletools.com/docs/reference/initialstate.md#toolpanel) | [`ToolPanelState`](https://www.adaptabletools.com/docs/reference/toolpanelstate.md) | Sets order &amp; visibility of Tool Panel controls in AdapTable ToolPanel (on right of grid) |
| [UserInterface](https://www.adaptabletools.com/docs/reference/initialstate.md#userinterface) | [`UserInterfaceState`](https://www.adaptabletools.com/docs/reference/userinterfacestate.md) | Controls the visibility of AdapTable UI elements (Dashboard, Tool Panel, Status Bar, Menus etc.) |

Provide `initialState` as an [`InitialState`](https://www.adaptabletools.com/docs/reference/initialstate.md) object in [Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md)

## How It Works

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

This storage can be locally or remotely depending on the [AdapTable State Persistence](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence/index.md)

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.

Although you can construct Initial State by hand, its often easier when building "complex" items like [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md) to create them in the GUI at design time and then copy and paste the resulting state

## Updating Initial Adaptable State

As the name implies, the concept behind Initial Adaptable State is that it provides — at design-time — the objects and theme for **initial** use of the Application.

[Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md) are configured in Adaptable Options, not in Initial State

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.

This is possible by using the `Revision` property.

See [Updating Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-updating-initial-state/index.md) for full details

## Providing Custom Data

The [Application State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-custom/index.md) 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.

This is a useful way to store additional data with your Initial Adaptable State e.g. user location, last updated time etc.

## Adaptable Objects

All objects in Initial Adaptable State inherit from [`AdaptableObject`](https://www.adaptabletools.com/docs/reference/adaptableobject.md).

- AdapTable Objects comprise most of the objects supplied in [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md) like Format Column
- However it also includes those objects which appear as Initial State properties (e.g. [Adaptable Style](https://www.adaptabletools.com/docs/ui-tutorial-providing-adaptable-style/index.md), [Button](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) etc.)

### Adaptable Object Properties

The `AdaptableObject` is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [AdaptableVersion](https://www.adaptabletools.com/docs/reference/adaptableobject.md#adaptableversion) | [`AdaptableVersion`](https://www.adaptabletools.com/docs/reference/adaptableversion.md) | Current AdapTable version |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/adaptableobject.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |
| [Metadata](https://www.adaptabletools.com/docs/reference/adaptableobject.md#metadata) | `any` | Optional metadata associated with the object; can be used to store additional information or configuration |
| [Source](https://www.adaptabletools.com/docs/reference/adaptableobject.md#source) | `'InitialState' \| 'User'` | Source of state object: &#39;InitialState&#39; if provided via `AdaptableOptions.initialState`, &#39;User&#39; or undefined for runtime state |
| [Tags](https://www.adaptabletools.com/docs/reference/adaptableobject.md#tags) | [`AdaptableObjectTag`](https://www.adaptabletools.com/docs/reference/adaptableobjecttag.md)`[]` | List of Tags associated with the Object |

#### 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.

If [Team Sharing](https://www.adaptabletools.com/docs/handbook-team-sharing/index.md) is enabled, any Adaptable Object can easily be shared at run-time between colleagues

- Do **not** set this property when writing objects in [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md)
- Instead, it will be set by AdapTable at run-time when the Initial State is first read

#### IsReadOnly

[Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md) in AdapTable typically operate at the [Module](https://www.adaptabletools.com/docs/technical-reference-adaptable-modules/index.md) level.

Each Module can be set to be `Full`, `ReadOnly` or `Hidden`

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 override the 'Full' Entitlement in the Module.

- There is no property for the opposite use case
- You cannot change an AdapTable object to be `Full` where the Module's Entitlement is `ReadOnly`

#### Source

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

Do not provide a value for this property in [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md) as it will be set by AdapTable at run-time

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

If an object is first supplied in Initial State and then later amended by the User in the UI, the value of the `Source` property will remain unchanged

#### Object Tags

Every Adaptable Object has a `Tags` property (of type [`AdaptableObjectTag`](https://www.adaptabletools.com/docs/reference/adaptableobjecttag.md)).

A Tag is a `string`. Use it to attach extra labels to any object you create.

The list of available Tags is set in [User Interface Options](https://www.adaptabletools.com/docs/technical-reference-ui/index.md) and is offered in the Settings Panel when creating or editing objects.

### `objectTags`

Tags that can be associated with Adaptable Objects

  `AdaptableObjectTag[] | ((context: ObjectTagsContext) => AdaptableObjectTag[])`

A string list, or a function that returns one. Run-time users pick from this list when tagging an object.

```ts {3}
userInterfaceOptions: {
  objectTags: ['team', 'production', 'experimental'],
},
```

#### Object Metadata

Every Adaptable Object has a `Metadata` property.

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

This is most commonly used to add extra information to [Layouts](https://www.adaptabletools.com/docs/handbook-layouts-extending/index.md) (e.g. team)

#### 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

Most AdapTable Objects can be **suspended**.

- Suspending an AdapTable Object turns off the current application of the object but keeps the definition in State
- This allows it easily to be re-activated without needing to be re-created or redefined

This is done by setting the `IsSuspended` property to true (or  by clicking Suspend button in the UI).

See [Suspending Adaptable Objects](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-suspending/index.md) for full details and an accompanying demo

### FAQ

**What are Adaptable Objects**
An [Adaptable Object](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md#adaptable-objects) is an object created either by the user at run-time, or by developers at design-time, which are used by Adaptable Modules.
Export, Format Columns, Shortcuts, Alerts etc. are all Adaptable Objects.

**Is it possible to create our own Adaptable Objects?**
Yes it is and we expect you to. All Adaptable Objects are simple JSON objects so you can easily create your own objects in [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md) and then you can include them in the application.

**What do Adaptable Objects look like?**
Obviously all Adaptable Objects are different but they do all implement a common [Adaptable Object](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md#adaptable-objects) interface which has just a few basic properties useful to all objects (e.g. `Uuid`).

**Are we only able to save Adaptable Objects we create to the local browser cache?**
No - you can save AdapTable objects [to any remote location of your choice](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence/index.md) by using the State Options functions.

**Can we turn off an AdapTable Object without having to subsequently re-create it?**
Yes — where the object is [Suspendable](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-suspending/index.md), set `IsSuspended` to `true` (or use the Settings Panel / API). The object stays in Adaptable State but is inactive.

**How do I know when an Adaptable Object has changed?**
By listening to the [Adaptable State Changed Event](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-events/index.md)
