Predefined Config Overview

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.

note

Predefined Config is provided to AdapTable via the predefinedConfig property in Adaptable Options

tip

Predefined Config can be provided 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 ConfigState (e.g. ConditionalStyle, Layouts etc.)

important

Config if only required for those State elements which require initial state

warning

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)

note

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.

tip

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

Revision Property

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.

caution

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.

tip

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:

export default {
.....
CustomSort: {
// This will replace the Custom Sort section in User State with the provided State
// but only if the Revision Number is greater than the one currently in User State
Revision: 2,
CustomSorts: [
{
ColumnId: 'Rating',
SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
},
],
},
.....
} as PredefinedConfig;

Adaptable Object

Most objects in AdapTable implement the Adaptable Object interface.

This contains a number of useful properties like Uuid, IsReadOnly and IsSuspended.

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.

note

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:

State PropertyDetails
AlertProvide Alert Definitions which will trigger run-time alerts
ApplicationSave your own state as key / value pairs
CalculatedColumnCreate custom columns with dynamic values based on expression
ConditionalStyleDynamically Style columns & rows according to rules provided
CustomSortBuild your own sort orders for columns with non-standard sorts
DashboardConfigure & populate the Dasboard area (above the main grid)
DataSourceProvide Data Sources that will populate Grid via the server
ExportCreate reports to export data from grid to numerous loctions
FilterManages creation & saving of System and Column filters
FormatColumnStyle a column so it always has a particular set of colours
FreeTextColumnSpecial free entry columns (e.g. Comments) saved with state
LayoutNamed views of column sorts, order, pivots, visbility & groups
PlusMinusSpecify how cells will nudge when '+' and '-' keys are pressed
QueryCreate saveable multi-column searches with multiple criteria
QuickSearchRun a text based search across whole grid (using wildcards)
ScheduleSchedule alerts to run to remind you of actions to perform
ShortcutAvoid fat finger issues by creating keyboard shortcuts
ThemeSelect with shipped Theme is used or provide a custom one
ToolPanelManage AdapTable ToolPanel (the area to the right of grid)

Charts Predefined Config

State PropertyDetails
ChartVisualise grid data using a variety of different chart types
SparklineColumnSee columns containing ranges of data as a sparkline

Predefined Config Example

export default {
Dashboard: {
Tabs: [
{
Name: 'Search',
Toolbars: ['QuickSearch', 'DataSource', 'Query'],
},
{
Name: 'Edit',
Toolbars: ['BulkUpdate','SmartEdit'],
},
{
Name: 'Grid',
Toolbars: ['Layout', 'CellSummary', 'SystemStatus']
},
],
},
QuickSearch: {
QuickSearchText: 'g',
Style: {
BackColor: '#ffff00',
ForeColor: '#8b0000',
},
},
Export: {
CurrentReport: 'High Freight',
Reports: [
{
Name: 'High Freight',
ReportColumnScope: 'ScopeColumns',
ReportRowScope: 'ExpressionRows',
Scope: {
ColumnIds: [
'OrderId',
'ChangeLastOrder',
'ContactName',
'InvoicedCost',
'OrderDate',
],
}
Query:{
BooleanExpression: '[Freight]> 500'
}
},
],
},
CustomSort: {
Customsorts: [
{
ColumnId: 'Employee',
SortedValues: [
'Margaret Peacock',
'Steven Buchanan',
'Janet Leverling',
],
},
],
},
ConditionalStyle: {
ConditionalStyles: [
{
Scope: { DataTypes: ['Number'] },
Style: {
ForeColor: '#008000',
},
Rule: {
Predicate: { PredicateId: 'Positive' },
}
},
{
Scope: { DataTypes: ['Number'] },
Style: {
ForeColor: '#ff0000',
},
Rule: {
Predicate: { PredicateId: 'Negative' },
}
},
{
Scope: { ColumnIds: ['InvoicedCost'] }
Style: {
BackColor: '#ffffcc',
FontStyle: 'Italic',
ForeColor: '#000000',
},
Rule:{
BooleanExpression: '[InvoicedCost]> 2000 AND [ItemCount] > 30'
}
},
],
},
Layout: {
CurrentLayout: 'Orders View',
Layouts: [
{
Columns: [
'OrderId',
'OrderDate',
'CustomerReference',
'CompanyName',
'ContactName',
'InvoicedCost',
'ChangeLastOrder',
'OrderCost',
'PackageCost',
'ItemCost',
'ItemCount',
],
Name: 'Orders View',
},
{
Columns: [
'OrderId',
'ShipVia',
'Freight',
'ShipName',
'ShipCountry',
'ShippedDate',
'CustomerReference',
],
ColumnSorts: [
{
Column: 'ShipName',
SortOrder: 'Asc',
},
],
Name: 'Shipping View',
},
],
},
FormatColumn: {
FormatColumns: [
{
Scope: { ColumnIds: ['OrderId'] },
Style: {
BackColor: '#d4fb79',
ForeColor: '#8b0000',
},
},
],
},
} as PredefinedConfig;

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.

important

Objects in Predefined Config are always written in PascalCase (as opposed to Adaptable Options which uses camelCase)

Suspending Config Objects

Objects provided in Predefined Config will operate immediately that the Application starts.

So any Conditional Styles will be immediately applied, any Layouts and Reports will be available for selection and any Alerts will fire.

And - depending on Entitlements they can be edited and deleted.

But sometimes you might wish just to suspend temporarily an object rather than delete it altogether.

This is done via the IsSuspended property of Suspendable Object (which derives from Adaptable Object) and can be set programmatically or in the UI.

More Information