Using AdapTable

important

This page is referring to how to set up an instance of AdapTable using core JavaScript. If using a Framework Wrapper the process is very similar conceptually but with some subtle differences.

See React Wrapper or Angular Wrapper for precise instructions.

caution

If you are using TypeScript to access AdapTable then you must use version 3.8.3 or higher

Creating an instance of AdapTable is straightforward and involves just 5 steps:

  1. Create <div /> elements in your HTML for Adaptable and the underlying vendor grid.
  2. Popular a vendor Data Grid instance with a column schema, row data and any properties set.
  3. Write any Predefined Config that you want your AdapTable instance to contain at start-up
  4. Create an Adaptable Options object, passing it the vendorGrid and predefinedConfig properties.
  5. Instantiate AdapTable - passing in the AdaptableOptions object and retrieving an Adaptable Api object for programmatic, run-time access to the tool.

This will then provide you with a fully working AdapTable instance together with an Adaptable API object which provides programmatic, run-time access.

Lets look at each of these in trun:

note

We will use ag-Grid in this example - by far the most popular and feature-rich DataGrid on the market.

Creating Div Elements

You need to create 2 <div /> elements in your HTML:

  • adaptable: will contain the AdapTable instance and is typically positioned first
  • grid: will contain the underlying vendor DataGrid; try to name this 'grid' if possible
<body>
....
<!-- div for adaptable - always name this 'adaptable'-->
<div id="adaptable"></div>
<!-- div for underlying vendor grid - always name this 'grid'
and add the default ag-Grid Theme (here 'alpine') -->
<div id="grid" class="ag-theme-alpine"></div>
....
</body>
tip

If using a Shadow DOM or some other mechanism where you cannot create the Div elements directly then use Container Options to pass in the 'adaptable' and 'grid' divs.

This accepts either the name of the Div or the HTMLElement itself.

Define Vendor DataGrid

It is your responsibility to set up the underlying vendor Data Grid object.

warning

Do not instantiate this vendor grid object. AdapTable will do that later together in its constructor together with any wiring up that might be required.

You should define any columns, set any properties, wire up grid events and perhaps provide it with initial data.

This will then be provided to AdapTable via the vendorGrid property of Adaptable Options.

Column Types

When defining the column schema in the Columns property of GridOptions it is advisable to add a ColumnType property for each column which matches an AdapTable Column Type.

note

This is not strictly required; however it helps AdapTable know definitively the Data Type of the column which will influence which filters and column options are available.

tip

This is advisable to use in all scenarios; however it's particularly important when the data is loaded after columns have already been set up, as AdapTable might have incorrectly inferred column data types.

caution

If a ColumnType property is not provided, AdapTable will look at the first row of the DataSet to evaluate the Data Type - this can occasionally cause issues on empty or 'mixed' columns.

const gridOptions: GridOptions = {
columnDefs: [
{
headerName: 'Make',
field: 'make',
filter: true,
editable: false,
type: 'abColDefString',
},
{
headerName: 'Released',
field: 'released',
filter: true,
editable: false,
type: 'abColDefDate',
},
{
headerName: 'Price',
field: 'price',
filter: true,
editable: true,
type: 'abColDefNumber',
},
{
headerName: 'Automatic',
field: 'automaticTransmission',
filter: true,
editable: false,
type: ['abColDefBoolean', 'checkboxType']
},
],
}

The AdapTable ColumnTypes are:

  • abColDefNumber: for numeric columns
  • abColDefNumberArray: for numeric array columns (used in Sparkline Columns)
  • abColDefString: for string (text) columns
  • abColDefBoolean: for boolean (yes/no) columns
  • abColDefDate: for data and time columns
  • abColDefObject: for any other column
tip

The type property can accept an array allowing you to provide your own types as well as those which AdapTable expects - as shown in the last column in example above

important

In Versions of AdapTable prior to 7.3 it was necessary also to add a ColumnTypes section in GridOptions - see Troubleshooting FAQ for an example.

Provide Predefined Config

Add any Predefined Config to ship AdapTable to meet your requirements for first use.

In this example we do the following:

  • Set 3 Dasbhboard Tabs - with 'Grid', 'Edit' and 'Search' related Toolbars respectively
  • Created a Layout with Row Grouping for the Make and Aggregation for Price columns
  • Provided a Display Format for the 'Price' column
  • Set a default System Status message of type 'Success'
const demoConfig: PredefinedConfig = {
Dashboard: {
Tabs: [
{
Name: 'Grid',
Toolbars: ['Layout', 'Export', 'CellSummary', 'Alert', 'Chart'],
},
{
Name: 'Edit',
Toolbars: ['SmartEdit', 'BulkUpdate'],
},
{
Name: 'Search',
Toolbars: ['Query', 'Filter', 'QuickSearch'],
},
],
},
Layout: {
CurrentLayout: 'Cars',
Layouts: [
{
Columns: [
'Model',
'Price',
'Make',
],
RowGroupedColumns: ['Make'],
AggregationColumns: { Price: 'sum'},
Name: 'Cars',
},
],
},
FormatColumn: {
FormatColumns: [
{
Scope: {
ColumnIds: ['Price'],
},
DisplayFormat: {
Formatter: 'NumberFormatter',
Options: {
FractionDigits: 0,
},
},
},
],
},
SystemStatus: {
DefaultStatusMessage: 'All working fine',
DefaultStatusType: 'Success',
},
} as PredefinedConfig;

Create AdapTable Options object

Create an AdaptableOptions object which defines how AdapTable should work and contains all it needs

Set any mandatory properties (e.g. adaptableId, primaryKey etc.) and add values for any non-mandatory properties where the default values are not appropriate.

Pass in the 'vendorGrid' object created in Step 2 (together with any Modules you need), and the 'predefinedConfig' (created above).

Also add any Plugins you want to include (in this example the Charts Plugin).

const adaptableOptions: AdaptableOptions = {
primaryKey: 'model',
userName: 'Demo User',
adaptableId: 'Basic Setup Demo',
userInterfaceOptions: {
adaptableToolPanelTitle: 'Grid Settings',
},
predefinedConfig: demoConfig,
vendorGrid: { ...gridOptions, modules: AllEnterpriseModules },
plugins: [ChartsPlugin()],
};

Instantiate AdapTable

AdapTable has a single, asynchronous static contstructor

This receives the Adaptable Options object as its only argument and returns (via a Promise) an Adaptable API object - which gives run time access to all AdapTable functionality.

const api: AdaptableApi = await Adaptable.init(adaptableOptions)

Access AdapTable at run-time

The AdapTable API has hundreds of methods to allow full programmatic access to AdapTable methods, events and state.

tip

One common practice is to subscribe to the Adaptable Ready event in order to perform any actions required at startup.

// Listen to the 'AdaptableReady' event via the EventAPI
// then use QuickSearchAPI to run a quick search for any cell containing 'toy'
adaptableApi.eventApi.on('AdaptableReady', () => {
adaptableApi.quickSearchApi.applyQuickSearch('toy');
});

Putting It All Together

This example shows all the above steps.

<body>
....
<div id="adaptable"></div>
<div id="grid" class="ag-theme-alpine"></div>
....
</body>
// Import Adaptable Styles
// You will always need to import 'index.css';
// Import 'dark.css' for our dark theme
// Tthese are the 2 shipped themes AdapTable provides - but you can add your own
// If you do create a custom theme then add the .css file here
import '@adaptabletools/adaptable/index.css';
import '@adaptabletools/adaptable/themes/dark.css';
// Import ag-Grid Styles you require
// In this case its the Balham light and dark themes (our defaults)
import '@ag-grid-community/all-modules/dist/styles/ag-grid.css';
import '@ag-grid-community/all-modules/dist/styles/ag-theme-balham.css';
import '@ag-grid-community/all-modules/dist/styles/ag-theme-alpine.css';
import '@ag-grid-community/all-modules/dist/styles/ag-theme-balham-dark.css';
import '@ag-grid-community/all-modules/dist/styles/ag-theme-alpine-dark.css';
// Import the Adaptable object from the appropriate vendorGrid sub folder
// We are using ag-Grid in thsi example so import that
import Adaptable from '@adaptabletools/adaptable/agGrid';
//Import any Adaptable types required
import {
AdaptableOptions,
PredefinedConfig,
AdaptableApi,
} from '@adaptabletools/adaptable/types';
// Import ag-grid objects from Community
// This is always required by AdapTable and must be installed
import { GridOptions, ColDef } from '@ag-grid-community/all-modules';
// Import any ag-Grid Enterprise modules you need
// You can add as many individual Enterprise modules as you wish
// Alternatively (as in this case) import AllEnterpriseModules
import { AllEnterpriseModules } from '@ag-grid-enterprise/all-modules';
// Import any Adaptable plugins that we want to use - in this case 'ChartsPlugin'
import ChartsPlugin from '@adaptabletools/adaptable-plugin-charts';
// Now put it all together...
export default async () => {
// Create the ag-Grid GridOptions object
// Define columns and provide data but DON'T instantiate it
const gridOptions: GridOptions = {
columnDefs: [
{
headerName: 'Make',
field: 'make',
filter: true,
editable: true,
type: 'abColDefString',
},
{
headerName: 'Model',
field: 'model',
filter: true,
editable: true,
type: 'abColDefString',
},
{
headerName: 'Price',
field: 'price',
filter: true,
editable: true,
type: 'abColDefNumber',
},
],
rowData: [
{ make: 'Toyota', model: 'Yaris', price: 40000 },
{ make: 'Toyota', model: 'Corolla', price: 28000 },
{ make: 'Ford', model: 'Mondeo', price: 32000 },
{ make: 'Ford', model: 'Fiesta', price: 35000 },
{ make: 'Ford', model: 'Focus', price: 26750 },
{ make: 'Ford', model: 'Galaxy', price: 41000 },
{ make: 'Porsche', model: 'Boxter', price: 72500 },
{ make: 'Porsche', model: 'Mission', price: 81000 },
{ make: 'Mitsubbishi', model: 'Outlander', price: 97800 },
],
enableRangeSelection: true,
sideBar: true,
suppressAggFuncInHeader: true,
suppressMenuHide: true,
};
// Create Predefined Config to ship AdapTable with at start-up
const demoConfig: PredefinedConfig = {
Dashboard: {
Tabs: [
{
Name: 'Grid',
Toolbars: ['Layout', 'Export', 'CellSummary', 'Alert', 'Chart'],
},
{
Name: 'Edit',
Toolbars: ['SmartEdit', 'BulkUpdate'],
},
{
Name: 'Search',
Toolbars: ['Query', 'Filter', 'QuickSearch'],
},
],
VisibleButtons: [
'ConditionalStyle',
'CellValidation',
'CalculatedColumn',
'PieChart',
],
},
Layout: {
CurrentLayout: 'Cars',
Layouts: [
{
Columns: [
'Model',
'Price',
'Make',
],
RowGroupedColumns: ['Make'],
AggregationColumns: { Price: 'sum'},
Name: 'Cars',
},
],
},
FormatColumn: {
FormatColumns: [
{
Scope: {
ColumnIds: ['Price'],
},
DisplayFormat: {
Formatter: 'NumberFormatter',
Options: {
FractionDigits: 0,
},
},
},
],
},
SystemStatus: {
DefaultStatusMessage: 'All working fine',
DefaultStatusType: 'Success',
},
} as PredefinedConfig;
// Create an AdaptableOptions object
// Pass it the GridOptions and PredefinedConfig objects created above
const adaptableOptions: AdaptableOptions = {
primaryKey: 'model',
userName: 'Demo User',
adaptableId: 'Basic Setup Demo',
userInterfaceOptions: {
adaptableToolPanelTitle: 'Grid Settings',
},
predefinedConfig: demoConfig,
vendorGrid: { ...gridOptions, modules: AllEnterpriseModules },
plugins: [ChartsPlugin()],
};
// Instantiate AdapTable and receive an AdaptableApi object for runtime access
const adaptableApi: AdaptableApi = await Adaptable.init(adaptableOptions);
// Use the AdapTable API to listen to events and perform run-time actions
adaptableApi.eventApi.on('AdaptableReady', () => {
adaptableApi.quickSearchApi.applyQuickSearch('toy');
});
};