Custom Tool Panels

Summary

Custom Tool Panels are Tool Panels provided by Developers
They are provided in Tool Panel Options
They are hosted in the Adaptable Tool Panel Component

Developers are able to provide custom ToolPanels containing bespoke elements.

They are rendered inside the Adaptable ToolPanel Component alongside the Module ToolPanels.

Note

Once defined, Custom ToolPanels can be configured and used in the same way as Module ToolPanels

Wiring Up Custom Tool Panels

Custom Tool Panels are provided in a 2-step process:

The Custom Tool Panel is defined in customToolPanels in Tool Panel Options
The Custom Tool Panel is referenced in Tool Panel Initial State

Developer Guide

Wiring up a Custom Tool Panel

These are the 2 steps required to provide a Custom Tool Panel in AdapTable.

const adaptableOptions: AdaptableOptions = {
  toolPanelOptions: {
    customToolPanels: [
      {
        name: 'buttonCustomToolPanel',
        title: 'Quick Actions',
        buttons: [
          // Adaptable Buttons here
        ],
      },
      {
        name: 'bespokeContentCustomToolPanel',
        title: 'Custom Content',
        frameworkComponent: () => {
          // bespoke content; use render if AdapTable Vanilla
        },
      },
    ],
  },
};

Create the Tool Panel in Tool Panel Options

Create the Custom Tool Panel in customToolPanels in Tool Panel Options.

Add name — how the Tool Panel is internally referenced in AdapTable
Optionally add title — the label shown in the Tool Panel header
Add the content (either AdapTable Buttons or bespoke rendering)

initialState: {
  ToolPanel: {
    ToolPanels: [
      {
        Name: 'buttonCustomToolPanel',
        VisibilityMode: 'expanded',
      },
      {
        Name: 'bespokeContentCustomToolPanel',
        VisibilityMode: 'collapsed',
      },
    ];
  }
}

Add Tool Panel and set visibility in Initial Adaptable State

Reference the Custom Tool Panel in Tool Panel Initial State.

Use the name supplied in Tool Panel Options.

Optionally configure the Tool Panel to display as expanded or collapsed.

Custom Tool Panel Contents

Custom Tool Panels can contain 2 different sets of content:

Buttons — an array of Adaptable Buttons
Bespoke content — for when more than buttons are required

Deep Dive

Anatomy of a Custom ToolPanel

The CustomToolPanel object is defined as follows:

Property	Type	Description
buttons	`AdaptableButton<CustomToolPanelButtonContext>[]`	Optional set of buttons to show in the ToolPanel
frameworkComponent	`AdaptableFrameworkComponent`	Framework-specific (Angular, React or Vue) component to be rendered
name	`string`	Name of Custom ToolPanel - should be unique
render	`(customRenderContext:CustomRenderContext) => string \| null`	Function to provide bespoke content when using AdapTable Vanilla
title	`string`	Title to display in Custom ToolPanel; if undefined, will default to `name` property

The name and title properties are self-explanatory.

buttons is used if the Custom ToolPanel will only contain Adaptable Buttons.

Otherwise the render function (AdapTable Vanilla) or frameworkComponent (all Frameworks) needs to be provided.

Providing AdapTable Buttons

Provide an array of Adaptable Buttons on the buttons property of CustomToolPanel.

This workflow is framework-agnostic — the same buttons configuration works for AdapTable Vanilla, React, Angular, and Vue.

Hint

If you only need a few actions in the Tool Panel, prefer buttons over bespoke render / frameworkComponent content

Developer Guide

Providing Custom Tool Panel Buttons

toolPanelOptions: {
  customToolPanels: [
    {
      name: 'ButtonToolPanel',
      title: 'Quick Actions',
      buttons: [
        {
          label: (button, context) =>
            context.adaptableApi.themeApi.getCurrentTheme() === 'light'
              ? 'Switch to Dark Theme'
              : 'Switch to Light Theme',
          onClick: (button, context) => {
            const themeApi = context.adaptableApi.themeApi;
            themeApi.getCurrentTheme() === 'light'
              ? themeApi.loadDarkTheme()
              : themeApi.loadLightTheme();
          },
          buttonStyle: {tone: 'accent', variant: 'raised'},
        },
        {
          label: 'Open Named Queries',
          onClick: (button, context) => {
            context.adaptableApi.namedQueryApi.openNamedQuerySettingsPanel();
          },
        },
      ],
    },
  ],
},

Add Adaptable Buttons to `buttons`

Supply an array of Adaptable Buttons on the buttons property.

Each button's label, onClick, and other callbacks receive a CustomToolPanelButtonContext with adaptableApi, the current Tool Panel State, and the hosting CustomToolPanel.

Deep Dive

Configuring Custom Tool Panel Buttons

As with all Adaptable Buttons, each button can be styled and configured with label, icon, onClick, hidden, disabled, and related properties.

Find Out More

See Adaptable Buttons for full configuration details

Button callbacks receive a CustomToolPanelButtonContext:

Property	Type	Description
customToolPanel	`CustomToolPanel`	The Custom ToolPanel which contains the button
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Custom Tool Panel: Using Buttons

Fork Fork

This example defines one Custom Tool Panel — Quick Actions — containing three AdapTable Buttons:
- Switch Theme — toggles light / dark theme
- Open Named Queries — opens the Named Query settings panel
- Show Date — displays today's date in an alert
The AdapTable Tool Panel opens on load so the Custom Tool Panel is visible

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolPanelButtonContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Tool Panel With Buttons',
  toolPanelOptions: {
    customToolPanels: [
      {
        name: 'ButtonToolPanel',
        title: 'Quick Actions',
        buttons: [
          {
            label: (
              button: AdaptableButton<CustomToolPanelButtonContext>,
              context: CustomToolPanelButtonContext
            ) =>
              context.adaptableApi.themeApi.getCurrentTheme() === 'light'
                ? 'Switch to Dark Theme'
                : 'Switch to Light Theme',
            onClick: (
              button: AdaptableButton<CustomToolPanelButtonContext>,
              context: CustomToolPanelButtonContext
            ) => {
              const themeApi = context.adaptableApi.themeApi;
              themeApi.getCurrentTheme() === 'light'
                ? themeApi.loadDarkTheme()
                : themeApi.loadLightTheme();
            },
            buttonStyle: {tone: 'accent', variant: 'raised'},
          },
          {
            label: 'Open Named Queries',
            onClick: (
              button: AdaptableButton<CustomToolPanelButtonContext>,
              context: CustomToolPanelButtonContext
            ) => {
              context.adaptableApi.namedQueryApi.openNamedQuerySettingsPanel();
            },
            buttonStyle: {variant: 'outlined'},
          },
          {
            label: () => 'Show Date',
            onClick: (
              button: AdaptableButton<CustomToolPanelButtonContext>,
              context: CustomToolPanelButtonContext
            ) => {
              context.adaptableApi.alertApi.showAlertInfo(
                'Current Date',
                'Today is: ' + new Date().toLocaleDateString(),
              );
            },
            buttonStyle: {tone: 'info', variant: 'text'},
          },
        ],
      },
    ],
  },
  initialState: {
    ToolPanel: {
      ToolPanels: [
        {
          Name: 'ButtonToolPanel',
          VisibilityMode: 'expanded',
        },
        {
          Name: 'Layout',
          VisibilityMode: 'collapsed',
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Providing Bespoke Content

When Adaptable Buttons are not enough, you can provide bespoke HTML in a Custom Tool Panel.

This is done using the render property — a function that returns an HTML string (or null).

render?: (context: CustomRenderContext) => string | null;

The function receives CustomRenderContext defined as follows:

Property	Type	Description
element	`HTMLDivElement`	Container Div Element
phase	`'onMount' \| 'onDestroy'`	Phase of DOM Element lifecycle
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Note

On onMount, return markup for AdapTable to inject into the panel container (context.element)
On onDestroy, return null and run any teardown (for example removing listeners attached to context.element)

Developer Guide

Providing Bespoke Tool Panel Content

toolPanelOptions: {
  customToolPanels: [
    {
      name: 'ApplicationPanel',
      title: 'Application',
      render: context => {
        if (context.phase === 'onMount') {
          return '<label>Number of agents: <input type="text" placeholder="Enter count" /></label>';
        }
        return null;
      },
    },
  ],
},

Set `render` on the Custom Tool Panel

Provide a function on the CustomToolPanel that returns the HTML to display.

Return HTML on mount

When CustomRenderContext phase is 'onMount', return your markup.

Return null on destroy

When phase is 'onDestroy', return null. Use context.adaptableApi from CustomRenderContext if the panel needs to call AdapTable APIs.

Custom Tool Panel: Bespoke Content

Fork Fork

Two Custom Tool Panels use render only (no buttons):
- Hello World — static HTML returned from render
- Application — an input rendered on onMount using CustomRenderContext lifecycle
The AdapTable Tool Panel opens on load

Caution

Unlike Dashboard Toolbars, the close button on a Tool Panel is always visible (and not configurable)
Module Tool Panels always display the Configure button; Custom Tool Panels do not

AdapTable Resources

Adaptable Buttons
Building Custom Components
Custom Toolbars — similar pattern for providing bespoke content

PreviousModule Tool Panels NextTool Panel Buttons