AdapTable - Key Concepts

There are a few important concepts that you need to understand when working with Adaptable:

• configuring data and primary key
• state and state persistence
• views and available columns
• rendering the component

Configuring data and primary key

Obviously any DataGrid component needs data. This is a top-level prop, and your data can be one of the following:

• an array
• a Promise resolving to an array
• a function returning either of the above

<Adaptable.Provider data={data} primaryKey="id">
  ...
</Adaptable.Provider>

After specifying the data, you need to pass the primaryKey prop. This will be used to uniquely identify each row in your data.

You need to make sure the primary key values are unique, otherwise AdapTable will behave inconsistently. Many features of AdapTable rely on this uniqueness - for example, row selection, cell selection, editing, cell summary to name a few.

Understanding state and persistence

The Adaptable state (passed into the React component via the defaultState prop) determines how the component will look and behave.

By configuring the default state, you control how the user will initially see the AdapTable component. After the component is initialised, the user will interact with it and almost every interaction will update the state object internally (e.g.: changing column order, sorting, creating a new view).

The most important part of the state are the views. The state.view property is a mandatory property, as you need to have at least one view. The view contains an array of columns, which are references to the columns made available to the component via state.globalEntities.availableColumns.

The state.globalEntities.availableColumns is an object keyed by the column id, which contains all the columns that can be used in the views - each column describes the field it's bound to, the data type, whether it's sortable/pinned/groupable and more.

In turn, each view defines an array of columns, which are objects that refer to the available columns via the id. We call those column references.

import { Adaptable, type AdaptableColDef } from '@adaptabletools/adaptable-infinite-react';

// JavaScript Web frameworks
const availableColumns: Record<string, AdaptableColDef> = {
  id: { field: 'id', dataType: 'number' },
  name: { field: 'name', label: 'Name', dataType: 'text' },
  language: { field: 'language', dataType: 'text' },
  license: { field: 'license', dataType: 'text' },
  stars: {
    field: 'github_stars', editable: true, dataType: 'number'
  },
  '2xstars': { expression: '[github_stars] * 2', dataType: 'number' }
};

<Adaptable.Provider
  primaryKey="id"
  defaultState={{
    view: {
      currentViewId: 'tableView',
      views: [
        {
          id: 'tableView', label: 'Table View',
          columns: [
            { id: 'name' }, // reference the `name` column
            { id: 'stars', editable: false },
            { id: 'language' },
          ],
        }
      ]
    },
    globalEntities: {
      availableColumns,
    },
  }}
  adaptableId="Adaptable Demo"
  data={[...]}
>
</Adaptable.Provider>

State Persistence

After the component is initialised with the defaultState prop, AdapTable will manage the state internally and will persist it in the browser's local storage by default.

This behavior can be configured by specifying a custom persistState function. If you specify a custom persistState function to change the way the state is persisted (e.g. send it to your application server), you'll also need to pair it with the loadState function. loadState will be called when the AdapTable component is initialised and it should fetch the state from the persistence layer (e.g. from your application server) - it will do the exact opposite of persistState.

<Adaptable.Provider
  primaryKey="id"
  adaptableId="Basic State"
  persistState={async (context) => {
    const { state, stateKey } = context;
    await fetch(`https://my-server.com/save-state?key=${stateKey}`, {
      method: 'POST',
      body: JSON.stringify(state),
    });
  }}
  loadState={(context) => {
    const { stateKey } = context;
    return fetch(`https://my-server.com/load-state?key=${stateKey}`).then((response) =>
      response.json(),
    );
  }}
>
  <Adaptable.UI />
</Adaptable.Provider>

Understanding and configuring views

Views are the cornerstone of Adaptable. Almost everything you see in the DataGrid is controlled by the current view.

Adaptable can be configured with multiple views but only one view can be active at any given time.

The active view determines the visible columns, the column order, the row grouping, the filters, the sorting, which alerts are active, which conditional styles are active and more.

Views are configured via the (mandatory) view property in the default state. The columns in the view use their id to reference the available columns in state.globalEntities.availableColumns.

defaultState = {
  // configure Views here
  view: {
    currentViewId: 'myView',
    views: [
      {
        id: 'myView',
        label: 'My View',
        columns: [
          {
            // there's a `full_name` col already defined in the availableColumns
            id: 'full_name',
          },
          {
            id: 'description',
          },
        ],
      },
    ],
  },
};

Types of Views

AdapTable provides 2 types of views:

• Table Views - show columns in standard tabular format (can have row grouping, aggregations, etc.)

• Pivot Views - display data in pivoted, aggregated format

Each View is either a Table View or a Pivot View.

Rendering the component

After the data, primaryKey, defaultState and adaptableId are configured, you're ready to render the component.

To make it flexible, we're exposing the Adaptable state to your app via a context - that's the reason why you need to configure the <Adaptable.Provider /> will all of the above props, but also need to render a separate <Adaptable.UI /> inside it.

Basically you can render any other parts of your app inside the <Adaptable.Provider />, with the added benefit that you get access to the Adaptable state, via the useAdaptableState() React hook.

import { Adaptable } from '@adaptabletools/adaptable-infinite-react';

function App() {
  return <Adaptable.Provider {...}>
    <YourCmp> // <--- has access to useAdaptableState()
    <Adaptable.UI />
  </Adaptable.Provider>

import { useAdaptableState } from '@adaptabletools/adaptable-infinite-react';

const viewId = useAdaptableState((state) => state.view.currentViewId);

useAdaptableStateSubscribe({
  selector: (state) => state.view.currentViewId,
  callback: (viewId, oldViewId) => {
    console.log('view changed', viewId);
  },
});

import { useAdaptableApi } from '@adaptabletools/adaptable-infinite-react';

function App() {
  return (
    <Adaptable.Provider>
      <YourApp />
    </Adaptable.Provider>
  );
}
function YourApp() {
  const api = useAdaptableApi();

  const setLightTheme = () => {
    api.themeApi.setTheme('light');
  };

  return (
    <>
      <CustomCmp />
      <button onClick={setLightTheme}>set light theme</button>
      <Adaptable.UI />
    </>
  );
}