Typically developers will populate a new AdapTable instance with Predefined Configuration.
This means that when users open the new application, 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. It can be passed in either as pure JSON or as a url string to a file which contains the JSON.
How It Works
Predefined Config is created at design-time in JSON format. It consists of a series of (nullable) properties that themselves each implement Config State (e.g.
Only provide config for those state elements which require intial state - within each object every object is nullable (with default values) so only those elements which differ from the default implementation need to be provided.
The State items in Predefined Config can be conceptually be put into 2 categories:
Design-Time: Cannot be overriden and saved by users (e.g. Menus, Entitlements etc.)
Run-Time: Can be overriden and saved by user's actions (and persisted through State Management)
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 all your config by hand, its often easier when building more "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.
But this provides a problem for Predefined Config, because it is stored as JSON which means it can only contain elements which can be 'stringified' (and that excludes functions).
The solution is that the Predefined Config section will contain a named reference to the function but the actual implementation will be provided in the User Functions section of Adaptable Options.
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 a 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 Config State (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 (see example below).
Most objects in PredefinedConfig implement the
This has a single
Uuid property which is used for easy identification of objects and to make it easy for AdapTable instances to share state and inform each other when an item has been created / edited / deleted..
This is included by AdapTable in all base objects and also frequently used objects like Expressions.
Do not set this property when writing objects in your Predefined Config as it will be set by AdapTable at run-tine when the config is first read
If Team Sharing is enabled, then any Adaptable Object can easily be shared - at run-time - between colleagues.
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.
Predefined Configuration includes an 'Entitlements' section, allowing developers to stipulate which AdapTable functions users are allowed to access.
Entitlements can be set to 'Full', 'Hidden' or 'ReadOnly' and a default Entitlement can be provided.
See Entitlements Guide for more information.
Predefined Config Contents
|ActionColumn||No||Create dynamic columns with Buttons that fire events|
|Alert||Yes||Provide Alert Definitions which will trigger run-time alerts|
|Application||No||Save your own state as key / value pairs|
|BulkUpdate||Yes||Update multiple cells in a column to contain a new value|
|CalculatedColumn||Yes||Create custom columns with dynamic values based on expression|
|Calendar||Yes||Select or provide your own calendar for dealing with holidays|
|CellSummary||Yes||Choose which summary operations to see for selected cells|
|CellValidation||Yes||Provide (complex) rules to validate cell edits|
|ConditionalStyle||Yes||Dynamically Style columns & rows according to rules provided|
|CustomSort||Yes||Build your own sort orders for columns with non-standard sorts|
|Dashboard||Yes||Configure & populate the Dasboard area (abov the main grid)|
|DataSource||Yes||Provide Data Sources that will populate Grid via the server|
|Entitlements||No||Manage permissions so users only see relevant functions|
|Export||Yes||Create reports to export data from grid to numerous loctions|
|Filter||Yes||Manages creation & saving of System and Column filters|
|FlashingCell||Yes||Specify how cells will briefly flash as their values change|
|FormatColumn||Yes||Style a column so it always has a particular set of colours|
|FreeTextColumn||Yes||Special free entry columns (e.g. Comments) saved with state|
|GradientColumn||Yes||Style columns so that back colour is in ratio to cell contents|
|Layout||Yes||Named views of column sorts, order, pivots, visbility & groups|
|PercentBar||Yes||Columns which display a bar that is filled based on cell value|
|PlusMinus||Yes||Specify how cells will nudge when '+' and '-' keys are pressed|
|Query||Yes||Create saveable multi-column searches with multiple criteria|
|QuickSearch||Yes||Run a text based search across whole grid (using wildcards)|
|Schedule||Yes||Schedule alerts to run to remind you of actions to perform|
|Shortcut||Yes||Avoid fat finger issues by creating keyboard shortcuts|
|SmartEdit||Yes||Update multiple numeric cells with a single maths operation|
|SystemStatus||No||Show Messages and Alerts describing curent Status of the App|
|Theme||Yes||Select with shipped Theme is used or provide a custom one|
|ToolPanel||Yes||Manage AdapTable ToolPanel (the area to the right of grid)|
|UpdatedRow||Yes||Colour (and jump to) rows whose contents have changed|
|UserInterface||No||Provide your own menus, styles and colour palettes|
Charts Predefined Config
|Chart||Chart||Visualise grid data using a variety of different chart types|
|SparklineColumn||Chart||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.
- Application Data Entries Demo shows how to persist custom state information in Predefined Config.