Adaptable Options

Adaptable Options is a large group of property options designed to help developers set up AdapTable at design time so that it fits their precise requirements.

It provides the underlying Vendor Grid, Predefined Config and other information required to ensure a full, rich user experience.

note

AdapTable Options contains behaviour and functionality that will never change at run-time.

Predefined Config contains objects that users can amend and delete through the AdapTable UI.

It also enables advanced functionality like Team Sharing, Entitlements and AdapTable State Management

important

AdaptableOptions is the only object created that AdapTable requires to initialise and run; it is set up by developers at design-time and passed into the AdapTable constructor at startup.

The AdaptableOptions class consists of a few 'base' properties and a number of xxxOptions properties which are themselves collections of related properties (e.g. Search, Layout).

tip

Typically you will only need to populate a few of the properties in AdaptableOptions, and just a few properties in the xxxOptions classes.

note

Any property that is not supplied by the user when populating the object, will use the default value which is the most sensible and popular option.

Base Properties

The properties in the 'core' part of Adaptable Options are not grouped into a collection are as follows:

OptionDetails
licenseKeyLicense Key giving access to all functionality inside AdapTable
adaptableIdUnique Id for this instance of AdapTable
adaptableStateKeyLocalStorage key for storing of AdaptableState
autogeneratePrimaryKeyAutogenerates a Primary Key (if one cannot be provided)
predefinedConfigUser State shipped with AdapTable instance for first use
primaryKeyName of a column guaranteed to contain unique contents (mandatory)
userNameCurrent AdapTable user (useful for Audit purposes)
vendorGridUnderlying vendor grid instance, e.g. GridOptions for AG Grid (mandatory in Core)

licenseKey

All AdapTable users are provided with a License Key which gives full access to all the functionality in the tool.

When configuring AdapTable, this should be supplied as the licenseKey property.

warning

If the property is missing, AdapTable will display a watermark and run with reduced functionality

adaptableId

This is the identifier for the current instance of AdapTable

tip

This property is particularly useful for auditing, saving state remotely, or you are using multiple grids

If no value is supplied then the value will default to 'adaptable_id'

caution

The value for this property should not contain a '.' (as this value is used to name styles which raises issues if it contains a full stop).

note

The value provided here is also that used in the Dashboard Header if no value is supplied for homeToolbarTitle in Dashboard Options

adaptableStateKey

This is the identifier to be used as the localStorage persistence key for the AdaptableState.

note

If no value is provided for this property then the adaptableId property value (see above) is used

predefinedConfig

Predefined Config is User State configured and provided at design-time and shipped with AdapTable for initial use.

It contains a mixture of objects and properties.

important

The supplied value can be either a PredefinedConfig object or a url to the file which contains the config.

primaryKey

A mandatory property providing the name of a column in AdapTable guaranteed to contain unique values.

If one absolutely cannot be provided, set autogeneratePrimaryKey to true and AdapTable will create one.

See Primary Key for more information.

userName

The name of the current AdapTable user.

tip

Set this if using remote storage (via Server Options) to identify the current user

The property is also used in Audit to identify the user who has made edits or changed state.

vendorGrid

The underlying vendor grid or grid object which AdapTable will interact with.

important

If using AG Grid this is the GridOptions object

The object should contain all the column definitions and data sources required.

warning

This is a mandatory property (if using Adaptable 'Core')

caution

If using the React or Angular Wrapper, there is no need to populate this property (as gridOptions is a separate propery and AdapTable will wire up everything internally).

Options Collections

Most Options in Adaptable Options are gropued in relevant collections are follows:

OptionDetails
Container OptionsProperties that set where divs and components are located
Dashboard OptionsOptions for managing the Dashboard in AdapTable
Data Change History OptionsManages which data changes are monitored in Change History Module
Edit OptionsEditing (and server-editing) related options
Entitlements OptionsManage Entitlements to configure which AdapTable Modules users can access.
Export OptionsExporting and Report related Options
Filter OptionsManages Filtering in AdapTable
General OptionsGeneral set of Options (e.g. for managing Primary Keys
Layout OptionsLayout (Views) related Options
Menu OptionsOptions for managing Adaptable Column and Context Menus
Notification OptionsOptions relating to Notifications
Query Language OptionsOptions for managing the AdaptableQL
Search OptionsSearch related options (e.g. for managing Server searching)
State OptionsConfigures Remote State Management (in place of default local storage)
Team Sharing OptionsEnables 'Team Sharing' of AdapTable objects among colleagues
ToolPanel OptionsManage the AdapTable ToolPanel Component (that appears on right of grid)
User Interface OptionsUser Interface related functions (e.g. tool panels, toolbars)
Custom Predicate DefCustom predicates provided by devs (e.g. for filters, alerts etc.)

Plugin Options

These options are used by the AdapTable plugins

General Options

Most Adaptable Options are grouped according to theme (e.g. Layout, Menu, Filter).

But some did not fit into an obvious group so are bunched as General Options:

PropertyDescriptionDefault
alternativeModuleNamesAlternative names to use for Adaptable Modules in toolbars and menusnull
autoOrderGroupedColumnsSort Grouped Column automatically (using Custom Sort if one applied)true
caseSensitiveTextComparisonsMaintain upper and lower case when performing text operations (applies to both Expressions and Predicates)false
cellSummaryOperationsCustom Cell Summary Operations to add to shipped set
currentCalendarCalendar to use for calculating Holidays & Working Days'United Kingdom'
customSortComparersCustomSort column comparer functions
hideColumnWhenGroupedAutomatically removes a column from the grid when it becomes Row Groupedfalse
showGroupingTotalsAsHeaderShow aggregated totals row at top of Grid when row groupingfalse
showMissingColumnsWarningShow warning if AdapTable cannot find a columntrue
showMissingPrimaryKeyAlertShows Alert if Primary Key column in Adaptable Options is not present or incorrectfalse

The customSortComparers property can provide the Custom Sort Module with bespoke Column sorting.

The cellSummaryOperations property enables custom operations to be added to the Cell Summary Module.

Adaptable Warnings

General Options contains a couple of useful properties to manage Warnings that are displayed in the Console.

tip

See Logging for full information on how to configure console messages.

Missing Primary Keys

A Primary Key is an important concept in AdapTable as they ensure that each cell can in the grid can be uniquely identified.

So, by default, AdapTable displays a warning if the column identified as being Primary Key in Adaptable Options is missing from the Columns collection.

note

The Alert Module contains a PrimaryKeyDuplicate Predicate which will trigger when an already existing value is entered in the Primary Key column.

This behaviour can be overried by setting showMissingPrimaryKeyWarning to false:

generalOptions = {
showMissingPrimaryKeyWarning: false,
};
caution

The default value of true is recommended as a misapplied primaryKey can have many unpleasant side-effects, so only do this if absolutely required

Missing Columns

AdapTable will log a warning whenever a Column is referred to in Predefined Config or a Module which does not appear in the Grid.

This is usually required but there are are circumstances when this is not the case e.g.if columns get added to the grid piecemeal

To stop AdapTable from logging unnecessary warnings set showMissingColumnsWarning to false:

generalOptions = {
showMissingColumnsWarning: false,
};

Grouping Options

There are a few useful options related to Row Grouping.

Group Total Headers

showGroupingTotalsAsHeader is a useful option which will display any aggregated totals at the top of the Grid.

Setting this to true will display a pinned grouped total row at the top of the Grid as this demo illustrates.

tip

This is primarily for AG Grid users who want to see totals at the top of the grid, as currently grid aggregation is only available as a footer.

Auto Sort Group Columns

By default AdapTable automatically sorts row grouped Columns using the Column's default sort order.

note

This applies also to Columns with a Custom Sort which will be applied automatically

caution

If a defaultGroupSortComparator has been provided in GridOptions then this will always be used

Turn off this behaviour by setting autoOrderGroupedColumns to false.

Hide Empty Group Rows

Occasionally a Row Group might have no sub rows - this is often the case if there are nested groups.

When that happens AdapTable can be requested not to display the 'Open Group' arrow and display empty rows by setting hideEmptyGroupRows to true.

important

This functionality was deprecated in Version 10 as the AG Grid hook it used was removed in Version 26

Remove Column When Grouped

By default a column remains in its place in the Grid when it is Row Grouped.

This effective duplication of data can sometimes be unwelcome, particularly when space is at a premium.

note

It is particularly noticeable when groupDisplayType has been set to multipleColumns in GridOptions.

To change this behaviour, set the hideColumnWhenGrouped property to true.

When ungrouping the Column, it will automatically return to its previous place in the grid.

warning

The column will not revert to visible when ungrouped if the Layout was updated or switched

Grouping Example

// Change the defaults for Grouping behaviour
const adaptableOptions: AdaptableOptions = {
generalOptions: {
showGroupingTotalsAsHeader: true,
hideColumnWhenGrouped: true,
autoOrderGroupedColumns: false,
hideEmptyGroupRows: true,
},
};

Container Options

This section manages the 3 main div elements used by AdapTable - AdaptTable, VendorGrid and Modal.

It also contains options for showing items created by the Charts, Alert) and System Status Modules.

PropertyDescriptionDefault
adaptableContainerDiv containing AdapTable - string Id or HTMLElement"adaptable"
alertContainerDiv to show Alerts - string Id or HTMLElementundefined
chartContainerName of div where charts appear (if null, will be centre of page)undefined
modalContainerName of div where modals appear (if null, will be centre of page)undefined
systemStatusContainerDiv to show System Status messages - string Id or HTMLElementundefined
vendorContainerDiv containing underlying vendor grid- string Id or HTMLElement"grid"
vendorContainerWaitTimeoutUseful when the vendor grid is instantiated separately (eg: by vendor wrappers like React and Angular flavors). This is how long AdapTable waits for the vendor grid before giving up connecting to it.60s

All 6 options can be passed the name of the relevant Div element and some can also take the Div Element itself.

containerOptions = {
adaptableContainer: document.querySelector('#adaptable') as HTMLElement,
vendorContainer: 'vendorGridDiv',
modalContainer: 'modelDiv',
chartContainer: 'chartDiv',
};

Using a Shadow DOM

If using a package like stencil which uses a shadow DOM, vendorContainer and adaptableContainer should be specified as elements, rather than strings.

If scoped: true is set, then to retrieve references to vendor grid and adaptable container elements, use:

this.el.shadowRoot.querySelector(...)

If scoped: false is set, then it should be:

this.el.querySelector(...)

So the resulting code might look like this:

containerOptions.vendorContainer = this.el.querySelector('#grid')
containerOptions.adaptableContainer = this.el.querySelector('#adaptable')

More Information