Typically developers will populate a new AdapTable instance with Predefined Configuration.
This means that when end-users open the new application for the first time, they won't see an empty Grid but, rather, one pre-loaded with multiple Searches, Styles, Edit Rules, Reports etc. that match their needs and allow them to be productive immediately.
Predefined Config is provided to AdapTable via the
predefinedConfig property in Adaptable Options
Predefined Config can be provided either as pure JSON or as a url string to a file which contains the JSON
How It Works
Config if only required for those State elements which require initial state
The items in Predefined Config are those which can be overriden at run-time and saved by user's actions (and persisted through State Management)
Anything which cannot be changed at run-time is provided through Adaptable Options
When AdapTable is first loaded, any Predefined Config is read into memory and then stored - either locally or remotely depending on your settings (see the Adaptable State Guide for more information) - together with any user state that is created during that session.
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 config by hand, its often easier when building "complex" items like Queries to create them in the GUI at design time and then copy and paste the resulting state into your config file
The concept behind Predefined Config 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 developers might want to update one section in Predefined Config while ensuring that the rest of the user's State remains untouched.
This can be accomplished through the
Revision property in ConfigState (the base interface for all User State sections).
Simply put: if you increment (or provide from new) the revision number in a section of Predefined Config, AdapTable will replace that section (but only that section) in the user's State with the new Config.
This is replace only, so you cannot use Revisions to merge a new section (e.g. Layout) in Predefined Config with the user's persisted section in State.
But you can, for example, provide a new
CustomSort section in Predefined Config which will replace the user's Custom Sorts in State while keeping their Layouts and other state elements untouched:
Providing Custom State
The Application State property of Predefined Config 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.
Outdated Predefined Config
We try hard to ensure that all changes to Predefined Config are fully backwardly compatible.
However, occasionally, an enhancement request requires an update to Config which 'breaks' the previous State.
This only happens once a year at most and always only in a Major Version release
When this occurs, AdapTable will often automatically update the old Config to the new Config at application load and then save the updated version for future use, so the user sees nothing amiss.
Predefined Config Contents
The contents of the PredefinedConfig class is as follows:
|Alert||Provide Alert Definitions which will trigger run-time alerts|
|Application||Save your own state as key / value pairs|
|CalculatedColumn||Create custom columns with dynamic values based on expression|
|ConditionalStyle||Dynamically Style columns & rows according to rules provided|
|CustomSort||Build your own sort orders for columns with non-standard sorts|
|Dashboard||Configure & populate the Dasboard area (above the main grid)|
|DataSource||Provide Data Sources that will populate Grid via the server|
|Export||Create reports to export data from grid to numerous loctions|
|Filter||Manages creation & saving of System and Column filters|
|FormatColumn||Style a column so it always has a particular set of colours|
|FreeTextColumn||Special free entry columns (e.g. Comments) saved with state|
|Layout||Named views of column sorts, order, pivots, visbility & groups|
|PlusMinus||Specify how cells will nudge when '+' and '-' keys are pressed|
|Query||Create saveable multi-column searches with multiple criteria|
|QuickSearch||Run a text based search across whole grid (using wildcards)|
|Schedule||Schedule alerts to run to remind you of actions to perform|
|Shortcut||Avoid fat finger issues by creating keyboard shortcuts|
|Theme||Select with shipped Theme is used or provide a custom one|
|ToolPanel||Manage AdapTable ToolPanel (the area to the right of grid)|
Charts Predefined Config
|Chart||Visualise grid data using a variety of different chart types|
|SparklineColumn||See columns containing ranges of data as a sparkline|
Predefined Config Example
In this example we have configured the Dashboard, set the Smart Edit value, configured Quick Search and supplied Export (Reports), Custom Sort, Conditional Style, Layout and Format Column config objects.
Most objects in AdapTable implement the AdaptableObject interface.
This contains a number of useful properties like
This includes not only objects supplied in Predefined Config like Conditional Style or Format Column, but also AdapTable objects that appear as config properties (e.g. Style, Button etc.)
The object contains just 3 properties:
|IsReadOnly||Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')|
|Source||Source of state object: 'Config' if provided via , 'User' or undefined for runtime state.|
|Uuid||Unique identifier for the Adaptable Object, generated and used internally by AdapTable|
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 is enabled, any Adaptable Object can easily be shared - at run-time - between colleagues
Do not set this property when writing objects in Predefined Config as it will be set by AdapTable at run-time when the config is first read
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 overrride the 'Full' Entitlement in the Module.
There is no property for the opposite use case - where the Module's Entitlement is 'ReadOnly' but one AdaptTable object should be 'Full'
Source property is applied by AdapTable and defines where the object was first created.
Do not provide a value for this property as it will be set by AdapTable at run-time
It can be of one of 2 values:
Config- the object was initially provided in Predefined Config
User- the object was created by the user - either at run-time in the UI or through the Adaptable Api
If an object is first supplied in Predefined Config and is then amended by the User the 'Source' value will remain unchanged
The interface exposes just a single -
IsSuspended - property:
|IsSuspended||Suspends (i.e. turns off) an Adaptable Object|
- Application Data Entries Demo shows how to persist custom state information in Predefined Config.