Predefined Config Overview

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.

note

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. ConditionalStyle, Layouts etc.

tip

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.

tip

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.

Providing Functions

Many objects in AdapTable (e.g Custom Sorts, User Menus, Action Columns etc.) include JavaScript that developers can provide when it makes sense to use a custom implementation rather than one provided by AdapTable.

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.

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

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 (see example below).

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.
},
{
ColumnId: 'Country',
CustomSortComparerFunction: 'country',
},
{
ColumnId: 'currency',
CustomSortComparerFunction: 'currency',
},
],
},
.....
} as PredefinedConfig;

AdaptableObject

Most objects in PredefinedConfig implement the AdaptableObject interface.

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.

warning

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.

Entitlements

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

State PropertySaveableDetails
ActionColumnNoCreate dynamic columns with Buttons that fire events
AlertYesProvide Alert Definitions which will trigger run-time alerts
ApplicationNoSave your own state as key / value pairs
BulkUpdateYesUpdate multiple cells in a column to contain a new value
CalculatedColumnYesCreate custom columns with dynamic values based on expression
CalendarYesSelect or provide your own calendar for dealing with holidays
CellSummaryYesChoose which summary operations to see for selected cells
CellValidationYesProvide (complex) rules to validate cell edits
ConditionalStyleYesDynamically Style columns & rows according to rules provided
CustomSortYesBuild your own sort orders for columns with non-standard sorts
DashboardYesConfigure & populate the Dasboard area (abov the main grid)
DataSourceYesProvide Data Sources that will populate Grid via the server
EntitlementsNoManage permissions so users only see relevant functions
ExportYesCreate reports to export data from grid to numerous loctions
FilterYesManages creation & saving of System and Column filters
FlashingCellYesSpecify how cells will briefly flash as their values change
FormatColumnYesStyle a column so it always has a particular set of colours
FreeTextColumnYesSpecial free entry columns (e.g. Comments) saved with state
GradientColumnYesStyle columns so that back colour is in ratio to cell contents
LayoutYesNamed views of column sorts, order, pivots, visbility & groups
PercentBarYesColumns which display a bar that is filled based on cell value
PlusMinusYesSpecify how cells will nudge when '+' and '-' keys are pressed
QueryYesCreate saveable multi-column searches with multiple criteria
QuickSearchYesRun a text based search across whole grid (using wildcards)
ScheduleYesSchedule alerts to run to remind you of actions to perform
ShortcutYesAvoid fat finger issues by creating keyboard shortcuts
SmartEditYesUpdate multiple numeric cells with a single maths operation
SystemStatusNoShow Messages and Alerts describing curent Status of the App
ThemeYesSelect with shipped Theme is used or provide a custom one
ToolPanelYesManage AdapTable ToolPanel (the area to the right of grid)
UpdatedRowYesColour (and jump to) rows whose contents have changed
UserInterfaceNoProvide your own menus, styles and colour palettes

Charts Predefined Config

State PropertyPluginDetails
ChartChartVisualise grid data using a variety of different chart types
SparklineColumnChartSee 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', 'appToolbar']
},
],
},
SmartEdit: {
SmartEditValue: 10,
},
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',
],
}
Expression: '[Freight]> 500'
},
],
},
CustomSort: {
Customsorts: [
{
ColumnId: 'Employee',
SortedValues: [
'Margaret Peacock',
'Steven Buchanan',
'Janet Leverling',
],
},
],
},
ConditionalStyle: {
ConditionalStyles: [
{
Scope: { DataTypes: ['Number'] },
Style: {
ForeColor: '#008000',
},
Predicate: { PredicateId: 'Positive' },
},
{
Scope: { DataTypes: ['Number'] },
Style: {
ForeColor: '#ff0000',
},
Predicate: { PredicateId: 'Negative' },
},
{
Scope: { ColumnIds: ['InvoicedCost'] }
Style: {
BackColor: '#ffffcc',
FontStyle: 'Italic',
ForeColor: '#000000',
},
Expression: '[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.

More Information