AdapTable Version:

Framework:

Custom Toolbars

Summary

Developers are able to provide Custom Toolbars to supplement the System Toolbars shipped by AdapTable
These are provided in Dashboard Options and can contain 2 types of content:
- an array of Adaptable Buttons
- full bespoke content
Once created, Custom Toolbars are treated as full Toolbars and can be placed in any Tab as needed

Custom Toolbars allow developers to provide their own bespoke content inside the AdapTable Dashboard.

Note

Custom Toolbars are treated the same as Module Toolbars and can be Pinned or placed in named Tabs
AdapTable will take care of ensuring the Toolbar displays / renders when it needs to

2 different sets of content can be provided to a Custom Toolbar:

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

Hint

Each Custom Toolbar contains 2 div elements - one for each method of providing content

customToolbars

CustomToolbar[]

Custom Toolbars to show in the Dashboard Header

CustomToolbar[]

Custom Toolbars are Toolbars which are provided at Design Time with bespoke content.

They can then be inserted into Dashboard Tabs and will be rendered by AdapTable as required.

const adaptableOptions: AdaptableOptions = {
  dashboardOptions: {
    customToolbars: [
      {
        name: 'Toolbar1',
        toolbarButtons: [
          {
            label: 'First Toolbar btn',
            buttonStyle: {
              variant: 'text',
              tone: 'success',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // provide onClick implementation
            },
            hidden: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // provide hidden implementation
            },
            disabled: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // provide disabled implementation
            },
          },
        ],
      },
      {
        name: 'Toolbar2',
        toolbarButtons: [
          {
            label: 'Second Toolbar btn',
            buttonStyle: {
              variant: 'raised',
              tone: 'accent',
            },
            icon: {
              height: 30,
              src: 'https://img.icons8.com/ios-glyphs/30/000000/sort.png',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // provide onClick implementation
            },
          },
        ],
      },
    ],
  },
};

Wiring Up Custom Toolbars

Custom Toolbars are provided in a 2-step process:

The Custom Toolbar is defined in Custom Toolbars in Dashboard Options
The Custom Toolbar is referenced in Dashboard Initial State

Caution

This 2-step process is also used if displaying buttons in AdapTable React, AdapTable Angular or AdapTable Vue
However additional steps are required to display bespoke content - see React, Angular or Vue Components

Developer Guide

Providing a Custom Toolbar in AdapTable Vanilla

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

const adaptableOptions: AdaptableOptions = {
  dashboardOptions: {
    customToolbars: [
      {
        name: 'buttons_toolbar',
        title: 'Buttons',
        toolbarButtons: [
        {
          label: 'First Toolbar btn',
          buttonStyle: {
            variant: 'text',
            tone: 'success',
          },
          onClick: (button: AdaptableButton<CustomToolbarButtonContext>, context: CustomToolbarButtonContext) => {
            // provide onClick implementation
          },
          hidden: (button: AdaptableButton<CustomToolbarButtonContext>, context: CustomToolbarButtonContext) => {
            // provide hidden implementation
          },
          disabled: (button: AdaptableButton<CustomToolbarButtonContext>, context: CustomToolbarButtonContext) => {
            // provide disabled implementation
          },
        },
        ]
     },
  }],
 }
}

Create the Toolbar in Dashboard Options

Create the Custom Toolbar in the customToolbars property in Dashboard Options.

This has a number of properties including:

name - how the Toolbar is internally referenced in AdapTable
title - how the Toolbar is referenced in the AdapTable UI

initialState: {
  Dashboard: {
    Tabs: [
      {
        Name: 'Demo',
        Toolbars: ['buttons_toolbar'],
      },
    ];
  }
}

Add Toolbar and set Visibility in Initial Adaptable State

Reference the Custom Toolbar in AdapTable's Dashboard.

Use the value supplied as the name property in Dashboard Options:

You can set the Custom Toolbar as:

a Dashboard Tab; or
a Pinned Toolbar

Providing AdapTable Buttons

In this option, you simply provide an array of Adaptable Buttons to be displayed in the toolbarButtons property of Custom Toolbar.

Hint

If you require just to display a few buttons in the Custom Toolbar then use this option

Deep Dive

Configuring Custom Toolbar Buttons

As with all Adaptable Buttons, the button can be styled to user requirements with many properties and functions available to configure visibility, styling, onClick and other features.

Find Out More

See the Adaptable Buttons for full details on configuring buttons

All the Button's functions receive as context a bespoke CustomToolPanelButtonContext object which is defined as follows:

Property	Description
customToolbar	Custom Toolbar which hosts the Button
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

In this example we create a Custom Toolbar - Buttons - which contains 2 AdapTable Buttons (which have been given different styles):
- Switch Theme - the Text (and click action) changes based on the Current Theme
- Show Date - shows todays's date as a notification; the label updates every second to display the current time

Expand to see the Adaptable Button definitions

The Custom Toolbar is defined in Dashboard Options:

dashboardOptions: {
  customToolbars: [
    {
      name: 'ButtonToolbar',
      title: 'Buttons',
      toolbarButtons: [
        {
          label: (
            button: AdaptableButton<CustomToolbarButtonContext>,
            context: CustomToolbarButtonContext
          ) => {
            return context.adaptableApi.themeApi.getCurrentTheme() == 'light'
              ? 'Switch to Dark Theme'
              : 'Switch to Light Theme';
          },
          onClick: (
            button: AdaptableButton<CustomToolbarButtonContext>,
            context: CustomToolbarButtonContext
          ) => {
            context.adaptableApi.themeApi.getCurrentTheme() == 'light'
              ? context.adaptableApi.themeApi.loadDarkTheme()
              : context.adaptableApi.themeApi.loadLightTheme();
          },
          buttonStyle: {
            tone: 'accent',
            variant: 'raised',
          },
        },
        {
          label: () => {
           return 'Show Date at: ' + new Date().toLocaleTimeString();
          },
          onClick: (
            button: AdaptableButton<CustomToolbarButtonContext>,
            context: CustomToolbarButtonContext
          ) => {
            context.adaptableApi.alertApi.showAlertInfo(
              'Current Time',
              'Today is: ' + new Date().toLocaleDateString()
            );
          },
          buttonStyle: {
            tone: 'info',
            variant: 'text',
          },
        },
      ],
    },
  ],
},

and referenced in Initial Adaptable State:

initialState: {
  Dashboard: {
    Tabs: [
      {
        Name: 'Custom Tab',
        Toolbars: ['ButtonToolbar'],
      },
    ],
  },
},

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Toolbar With Buttons',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarActions: [],
        toolbarButtons: [
          {
            label: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              return context.adaptableApi.themeApi.getCurrentTheme() == 'light'
                ? 'Switch to Dark Theme'
                : 'Switch to Light Theme';
            },

            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.themeApi.getCurrentTheme() == 'light'
                ? context.adaptableApi.themeApi.loadDarkTheme()
                : context.adaptableApi.themeApi.loadLightTheme();
            },
            buttonStyle: {
              tone: 'accent',
              variant: 'raised',
            },
          },
          {
            label: () => {
              return 'Show Date at: ' + new Date().toLocaleTimeString();
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.alertApi.showAlertInfo(
                'Current Date',
                'Today is: ' + new Date().toLocaleDateString()
              );
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Custom Tab',
          Toolbars: ['ButtonToolbar'],
        },
      ],
    },

    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Automating Buttons

A common use case is for the AdapTable Buttons in a Custom Toolbar to be created dynamically.

For instance a user might want to render a button for each Named Query that is available.

Hint

The Dashboard API contains functions that enable Custom Toolbars to be accessed and easily updated
Listen to the Adaptable State Changed Event to be updated when objects change in Adaptable State

Caution

If you have changed a Toolbar progromatically, call refreshDashboard in Dashboard API to update the UI

This demo contains a (pinned) Custom Toolbar displaying a Button for each Named Query in Adaptable State; when clicked, it sets the Grid Filter to that Query
We provide 3 Named Queries in Named Query Initial State - JavaScript, Big Stars, Top Frameworks - and the demo renders a button for each (together with a Clear Filter Button)
Additional buttons will be created / removed as Queries are manipulated in the UI - achieved by listening to the Adaptable State Changed Event

Try It Out

Create a new Named Query and then click the new Button that is dynamically created to run the Expression as a Grid Filter
Click one of the Buttons and then edit the associated Named Query in the Expression Editor - note that the the filter automatically updates

Rendering Bespoke Content

If you require to display more than just a few buttons in the Custom Toolbar, there is an alternative which allows you to provide full custom rendering.

This is provided via the render property which is a JavaScript function that you provide and AdapTable will invoke as required.

Caution

This render property is only used when using AdapTable Vanilla
When using a Framework Wrapper, bespoke content is rendered using the frameworkComponent property

Find Out More

AdapTable React Components explains how to render bespoke Custom Toolbar content in AdapTable React
AdapTable Angular Components explains how to render bespoke Custom Toolbar content in AdapTable Angular
AdapTable Vue Components explains how to render bespoke Custom Toolbar content in AdapTable Vue

Deep Dive

Rendering Bespoke Custom Toolbar Content in AdapTable Vanilla

The render function is defined as follows:

  render?: ({visible, node, adaptableApi}: {
    visible: boolean;
    node: HTMLDivElement;
    adaptableApi: AdaptableApi;
  }) => string | null;

As can be seen the function provides a flag to state whether the toolbar is visible or not (and also the current Div Element and the Adaptable API if required), and returns a string for the content.

The render function will be called with visible: false when the toolbar becomes invisible (i.e. unmounted), so you can can do some cleanup in case you need to.

This demo contains a Tab (entitled Custom Tab) which contins 2 Custom Toolbars with custom rendering:
- Hello World - just contains text
- Bespoke Rendering - contins an input

Configuring Custom Toolbars

A Custom Toolbar can be configured to display up to 2 Buttons via the toolbarActions property of the CustomToolbar object (by default neither will display).

Close - closes the Custom Toolbar

Hint

If a Custom Toolbar is closed, you need to open the Dashboard page in the Settings Panel to put it back in a Tab

Configure - enables the Custom Toolbar to be configured

Note

When clicked it triggers the Custom Toolbar Configured Event allowing custom functionality to be performed

PreviousTabs & Toolbars NextDashboard Buttons

Framework: