AdapTable Basics

AdapTable - Key Concepts

Summary

  • When developing applications using AdapTable there are 3 basic concepts its useful to understand, namely:
    • Adaptable Options - how to configure your AdapTable instance
    • Adaptable Initial State - the objects you will provide to your application for first time use
    • Adaptable API - how to access AdapTable at run-time
  • Additionally there are other concepts which will help you to get the most out of Adaptable, including:
    • Adaptable State
    • Modules
    • Plugins
    • Events
    • AdapTableQL

Basic Concepts

There are many important concepts that its worth understanding as developers using AdapTable in order to get the most out of the tool, which we highlight on this page (with links to more information).

However 3 in particular are key to getting started and making AdapTable work for you:

Adaptable Options

Adaptable Options is a large group of property options which you can configure at design-time to set up AdapTable so that it fits the requirements or the containing application.

The available properties include the underlying Initial Adaptable State, the adaptableId and many groups of related options (e.g. Entitlements, Layout, Search, Edit, Menu etc.)

Hint

Many of the options are JavaScript functions which, if provided, AdapTable will invoke when required

Find Out More

Learn more about the options available in Adaptable Options Reference

Initial Adaptable State

Initial State is a group of objects written in JSON that you will define at Design Time.

Caution

Most Initial State is optional but the Layout section (with at least one Layout defined) is mandatory

It includes all the AdapTable Objects required for initial use of your hosted application e.g. Layouts, Filters, Reports, Alerts, Format Columns etc.

Note

  • Adaptable Initial State contains persistable objects and properties which can change during Application run-time
  • Adaptable Options contains behaviour and functionality that will never change post-creation

When an application starts for the first time, Initial Adaptable State is loaded, and then merged with any run-time changes effected by the user; which is then stored (and subsequently reloaded) as Adaptable State.

Find Out More

Learn how Initial State works in greater detail in Guide to using Adaptable State and the Initial State Reference

Adaptable API

The Adaptable API provides full, rich, programmatic, run-time access to all AdapTable functionality.

This allows you to access Adaptable State in a 'safe' manner.

Anything that is achievable in the AdapTable UI can be accomplised alternatively using the Adaptable API.

Indeed you can use Adaptable API connect to AdapTable's functionality via your own custom screens bypassing AdapTable's UI altogether

Find Out More

See the full contents of the Adaptable API in Technical Reference

Developer Guide

Fitting these 3 Key Concepts Together

These 3 concepts are linked together as follows when AdapTable is instantiated.

Note

  • This example uses AdapTable Vanilla but very similar patterns are used for AdapTable React, AdapTable Angular and AdapTable Vue
  • All create AdapTable Options and Initial State, but have different mechanisms for tying them in with AG Grid
const adaptableOptions: AdaptableOptions = {
  licenseKey: '<ADAPTABLE_LICENSE_KEY_HERE>', // license key you were given
  primaryKey: 'tradeId', // a unique column
  initialState: initialState, // Inital Adaptable State required
};
1
Configure AdapTable Options

Adaptable Options is required by the async static constructor to initialise and prepare AdapTable

const initialState: InitialState = {
  Dashboard: {
    Tabs: [{ Name: 'Grid', Toolbars: ['Layout', 'Pricing']}],
  },
  Layout: {
    CurrentLayout: 'Cars',
    Layouts: [
      {
        TableColumns: ['Model', 'Price', 'Make'],
        RowGroupedColumns: ['Make'],
        Name: 'Cars',
      },
    ],
  },
} as InitialState;
2
Provide Initial Adaptable State

Adaptable Options includes Initial Adaptable State as a mandatory property.

This must include a Layout, and in every real-world use case, additional objects.

const agGridConfig : AgGridConfig={
  gridOptions: gridOptions, // AG Grid GridOptions object
  modules: RECOMMENDED_MODULES // AG Grid modules required 
}
const api: AdaptableApi = await Adaptable.init(adaptableOptions, agGridConfig);
3
Manage run-time acccess through Adaptable API

The constructor asynchronously returns the Adaptable Api object to facilitate full run-time access to all AdapTable functionality

Other Key Concepts

There are some other concepts worth understanding in order to fully leverage what AdapTable offers:

Adaptable Events

Adaptable fires many Events to keep you fully informed of everything going on inside AG Grid.

Perhaps the most important and commonly-used are:

You can listen to as many Events as you require.

Adaptable Modules

Most of the functionality in AdapTable is organised through Modules.

These are essentially sets of discrete functionality e.g. Custom Sort, Column Filters, Smart Edit etc.

Each Module has its own section in the Settings Panel, and some commonly used Modules (e.g. Export, Cell Summary, Layout) also have their own Dashboard Toolbars and Tool Panels.

Entitlements

UI access to Modules is managed by Entitlements.

This allows you to decide for each Module whether it is Available, Hidden or ReadOnly in the UI.

Hint

Additionally you can set an Entitlement on each Adaptable Object for a finer-grained approach

Plugins

To reduce download size, functionality that is required by subsets of Adaptable users is placed in plugins.

This means that you only need to install the plugin if you require the functionality it contains.

Adaptable State

All changes made to user state at Run Time are automatically persisted by AdapTable for future use.

They are subsequently reapplied when the Application restarts.

You can choose to store this Adaptable State in any remote persistence location that you require.

Note

Adaptable State Options can be used to enrich this State or manage it in multiple custom ways

Layouts

A Layout is collection of Column visibility, order and related column properties (e.g. pinning).

Hint

Layouts can be either Table or Pivot and can be extending to include formatting and styling

Layouts are used by AdapTable to set up AG Grid to meet user requirements.

Caution

Every AdapTable instance must have at least one Layout

Predicates and Expressions

AdapTable provides 2 different rule engines - each with its own evaluation capability:

  • Predicates - used for relatively simply boolean evaluations (e.g. Column Filters)
  • Expressions - rich, human-readable, multi-column and multi-operator constructs used in more complicated scenarios like Calculated Columns

Note

Evaluations are evaluated by AdapTableQL - AdapTable's native Query Language

Customising AdapTable

AdapTable is designed to be very heavily customisable so that it can integrate smoothly with any application.

Adaptable Options has plenty of properties that allow you to configure everything to your precise requirements.

Additionally you are able to:

  • provide a Custom Theme - use CSS Variables to make AdapTable look exactly how you need

  • supply your own Column and Context menu items

  • customise the Dashboard with the Buttons, Tabs and Toolbars that you need for your application

  • create Custom Dashboard Toolbars or Tool Panels that will contain and render your bespoke content

  • provide custom sections to the Settings Panel to include your settings

...and much, much more

Logging

AdapTable logs many messages to the console.

Critical messages are always visible, but you can set up logging to specify that all messages (or just certain types of messages) are visible.

PreviousAdapTable BasicsNextAdapTable Users