Predefined Config

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;

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)

AdaptableObject

Most objects in AdapTable implement the AdaptableObject interface.

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

note

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:

PropertyDescription
IsReadOnlySets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')
SourceSource of state object: 'Config' if provided via , 'User' or undefined for runtime state.
UuidUnique identifier for the Adaptable Object, generated and used internally by AdapTable

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

important

If Team Sharing is enabled, any Adaptable Object can easily be shared - at run-time - between colleagues

caution

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

IsReadOnly

Entitlements in AdapTable are designed to operate at the Module level.

tip

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.

warning

There is no property for the opposite use case - where the Module's Entitlement is 'ReadOnly' but one AdaptTable object should be 'Full'

Source

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

caution

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
note

If an object is first supplied in Predefined Config and is then amended by the User the 'Source' value will remain unchanged

SuspendableObject

Some objects in AdapTable implement the Suspendable Object interface (itself which derives from the base Adaptable Object).

The interface exposes just a single - IsSuspended - property:

PropertyDescription
IsSuspendedSuspends (i.e. turns off) an Adaptable Object

More Information