Tool Panel

An alternative to using the Dashboard is the AdapTable ToolPanel Component.

important

The AdapTable ToolPanel Component has many of the same features as the Dashboard and is ideal for when screen estate is at a premium

The AdapTable ToolPanel Component is displayed in the AG Grid Sidebar - the collapsible area typically positioned at the right of the Grid.

caution

The AdapTable ToolPanel Component is only available when using AG Grid as the underlying vendor Grid

It contains 2 main sections:

  • Buttons: Either buttons which open an Adaptable Module or Custom Buttons provided by the User
  • ToolPanels: Either Module-related and shipped with AdapTable or user-provided Custom ToolPanels

AdapTable ToolPanel Component

There are a few things worth noting in regard to displaying, naming, styling, opening and configuring the AdapTable ToolPanel Component.

Displaying the Component

In order to ensure the AdapTable ToolPanel Component is available, follow these steps:

  1. Check that the Entitlement for the ToolPanel Module does not have an Access Level of Hidden

  2. Ensure that showAdaptableToolPanel in ToolPanel Options is set to true (the default value)

  3. Configure the Sidebar in AG Grid GridOptions

    caution

    AdapTable will automatically add the ToolPanel into the Sidebar if this property is set to 'true' or it contains the names of AG Grid ToolPanels; but not if the property is missing or set to 'false'

    const gridOptions: GridOptions = {
    ...
    // this will show the default AG Grid Toolbars: Filters and Columns
    sideBar: true,
    ...
    };
    const adaptableOptions: AdaptableOptions = {
    ...
    toolPanelOptions: {
    // This is the default value
    showAdaptableToolPanel: true
    },
    ...
    };

Framework Wrappers

warning

There are additional steps required if wanting to use the AdapTable ToolPanel with a Framework Wrapper.

See the relevant instructions for the React Wrapper and for the Angular Wrapper

Setting Component Name

By default the ToolPanel will display the word 'AdapTable'.

tip

This can be changed by providing a value for the adaptableToolPanelTitle property in the [ToolPanel Options]#toolpanel-options) section of Adaptable Options.

Component Icon Key

By default the AdapTable ToolPanel displays the 'menu' key - which appears as 3 vertical lines.

This can be changed by setting the iconKey property in the [ToolPanel Options]#toolpanel-options) section of Adaptable Options.

important

See the AG Grid documentation for details on how to Configure the Sidebar and Provide Custom Icons

Opening the Component

The AdapTable ToolPanel Component can be opened programatically at any time by calling the openAdapTableToolPanel method in ToolPanel API:

tip

This is most often done at startup by listening to the AdaptableReady Event

// Open the Adaptable ToolPanel Component on application startup
adaptableApi.eventApi.on('AdaptableReady', (info: AdaptableReadyInfo) => {
adaptableApi.toolPanelApi.openAdapTableToolPanel();
});

Configuring the Component

Clicking the Configure (wrench) button in the Adaptable ToolPanel Component will open the ToolPanel Popup.

This window contains 2 tabs:

ToolPanel Order

By default the Adaptable ToolPanel Component will be positioned after the AG Grid ToolPanels.

Use the toolPanelOrder property of [ToolPanel Options]#toolpanel-options) to supply a different order:

adaptableOptions.toolPanelOptions = {
// Display the Adaptable ToolPanel Component first
toolPanelOrder: ['AdaptableToolPanel', 'filters', 'columns'],
};
note

The default order is ['filters', 'columns', 'AdaptableToolPanel']

caution

This property does not automatically display the ToolPanels - that still has to be done as described above

ToolPanels

The main section of the AdapTable ToolPanel Component includes a number of different ToolPanels.

These 2 categories of ToolPanels:

Module ToolPanels

AdapTable provides these Module-related ToolPanels out of the box:

Use ToolPanel Predefined Config to specify which Module ToolPanels should be visible at start-up

tip

All Module ToolPanels are visible by default - only set this section if this is not required

const demoConfig: PredefinedConfig = {
ToolPanel: {
// Set just Layout and SmartEdit ToolPanels to be visible at start-up
ToolPanels: [
{
Name: 'Layout',
},
{
Name: 'SmartEdit',
},
],
},
};
note

Any Module ToolPanel not listed here is still available, and can be made visible at run-time by the User - provided, of course, that the Module does not have a 'Hidden' Entitlement

Visibility Mode

Each ToolPanel has 2 visibility modes:

  • expanded - the ToolPanel is open and the rendered contents are visibile
  • collapsed - only the Header of the ToolPanel is visible with an arrow to see full contents
important

By default all ToolPanels are collapsed when the Application starts

Use ToolPanel Predefined Config to specify if certain ToolPanels should be expanded on startup:

const demoConfig: PredefinedConfig = {
ToolPanel: {
ToolPanels: [
{
// Will be collapsed by default
Name: 'CustomToolPanel',
},
{
Name: 'Layout',
// Set it to be expanded at startup
VisibilityMode: 'expanded',
},
{
Name: 'SmartEdit',
// Ensure it is collapsed (the default)
VisibilityMode: 'collapsed',
},
],
},
};

Custom ToolPanels

Developers are able to provide at design time - via the customToolPanels property of ToolPanel Options - bespoke ToolPanels containing bespoke elements.

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

The CustomToolPanel object is defined as follows:

PropertyDescription
frameworkComponentFramework-specific (Angular or React) component to be rendered
nameName of Custom ToolPanel - should be unique
renderFunction to provide bespoke content when NOT using a Framework wrapper
titleTitle to display in Custom ToolPanel; if undefined, will default to name property
toolPanelButtonsOptional set of buttons to show in the ToolPanel

As can be seen it has self-explanatory name and title properties.

In a similar way to Custom Dashboard Toolbars it contains 2 properties that provide custom content:

  • toolPanelButtons - a standard set of Adaptable Buttons
  • render a bespoke function that is invoked by AdapTable to fetch content when needed
important

Each Custom ToolPanel is capable of rendering either or both of these content types

Providing AdapTable Buttons

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

tip

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

As with all Adaptable Buttons, the button can be styled to user requirements and contains 3 important JavaScript functions provided (at design-time) by Users for AdapTable to invoke when required:

  • onClick - what happens when the Button is clicked
  • hidden - whether or not the Button should be displayed
  • disabled - whether or not the Button should be enabled
note

The buttonStyle and label properties can also return functions allowing you to style and caption the Button differently depending on circumstances

All these functions receive as context a CustomToolPanelButtonContext object which is defined as follows:

PropertyDescription
customToolPanelThe Custom ToolPanel which contains the button
toolPanelStateCurrent ToolPanel State

Custom ToolPanel Buttons Example

const adaptableOptions: AdaptableOptions = {
toolPanelOptions: {
customToolPanels: :[
{
name: 'toolPanel1',
title: 'Tool Panel One',
toolPanelButtons: [
{
label: 'First ToolPanel Button',
buttonStyle: {
variant: 'text',
tone: 'success',
},
onClick: (button: AdaptableButton<CustomToolPanelButtonContext>,
context: CustomToolPanelButtonContext) => {
// provide onClick implementation
},
hidden: (button: AdaptableButton<CustomToolPanelButtonContext>,
context: CustomToolPanelButtonContext) => {
// provide hidden implementation
},
disabled: (button: AdaptableButton<CustomToolPanelButtonContext>,
context: CustomToolPanelButtonContext) => {
// provide disabled implementation
},
},
]
},
],
},
};

Rendering Bespoke Content

If you require to display more than just a few buttons in the Custom ToolPanel, 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 property is used when using AdapTable core and not one of the Framewwork Wrappers

tip

See Custom ToolPanels in React Wrapper or Custom ToolPanels in Angular Wrapper for details on how to provide custom ToolPanel content when using a Framework Wrapper.

The 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 ToolPanel 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 ToolPanel becomes invisible (i.e. unmounted), so you can can do some cleanup in case you need to.

const adaptableOptions: AdaptableOptions = {
toolPanelOptions: {
customToolPanels: [
{
name: 'hellowWorldToolPanel',
title: 'Hello World Example',
render: () => {
return '<div><label>Hello World!!!</label> </div>';
},
},
{
name: 'CustomToolPanel',
render: ({ node, adaptableApi, visible }) => {
if (!visible) {
console.log('unmount');
} else {
node.classList.add('custom-app-cls');
}
return '<b>Custom ToolPanel Content:</b>';
},
},
],
},
}

Framework Components

If using the React or Angular Wrapper the method of rendering bespoke custom ToolPanel content is different.

You need to populate the frameworkComponent property of Custom ToolPanel.

This can be one of 2 types:

Configuring Custom ToolPanels

Similar to with Module ToolPanels, ToolPanel Predefined Config is required to specify which Custom ToolPanels are visible at start-up:

const demoConfig: PredefinedConfig = {
ToolPanel: {
ToolPanels: [
{
Name: 'CustomToolPanel1',
},
{
Name: 'CustomToolPanel2',
},
{
Name: 'Layout',
},
],
},
};

ToolPanel Buttons

The area above the ToolPanels can display Buttons. These can be of 2 types:

Module Buttons

This is a series of Buttons - there is one available for each Module which opens the associated popup.

The Module Buttons displayed can be set via the ModuleButtons property in ToolPanel Predefined Config:

note

By default no Module Buttons are displayed

const demoConfig: PredefinedConfig = {
ToolPanel: {
ModuleButtons: ['CustomSort', 'Export'],
},
};

Custom Buttons

Users can supply their own bespoke Buttons to appear in the Adaptable ToolPanel.

These are provided via the customToolPanelButtons property of ToolPanel Options.

Each button is of type Adaptable Button - used in multiple places in AdapTable - and defined as follows:

PropertyDescription
buttonStyleStyle for Button - can be object or function thats provides a Style object
disabledFunction that disables / enables the button based on its evaluation result
hiddenFunction which sets whether Button is hidden
iconIcon to display, requires string for URL, other props are optional
labelLabel for Button - can be string or function that provides string
onClickFunction to invoke when button is clicked
tooltipTooltip for Button - can be string or function that provides string
caution

Unlike with Custom ToolPanels, Custom Buttons do not need to be provided in Predefined Config - any which are supplied in ToolPanel Options are displayed automatically

All these functions receive as context a ToolPanelButtonContext object which just contains one property:

PropertyDescription
toolPanelStateCurrent ToolPanel State
const adaptableOptions: AdaptableOptions = {
toolPanelOptions: {
customToolPanelButtons: [
{
label: 'Query Editor',
icon: {
src: 'https://img.icons8.com/glyph-neue/64/000000/zoom-in.png',
},
hidden: (button: AdaptableButton<ToolPanelButtonContext>,
context: ToolPanelButtonContext) => {
return context.api.themeApi.getCurrentTheme() !== 'dark';
},
onClick: (button: AdaptableButton<ToolPanelButtonContext>,
context: ToolPanelButtonContext) => {
context.api.internalApi.dispatchReduxAction(
PopupRedux.PopupShowScreen(
ModuleConstants.QueryModuleId,
'ExpandedQueryPopup',
{
source: 'Other',
value: '',
},
{
footer: null,
}
)
);
},
},
],
},
},

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that the The Adaptable ToolPanel cannot be configured. Individual ToolPanels cannot be hidden or re-ordered.

note

With a ReadOnly Entitlement, individual ToolPanels can still be opened and closed

ToolPanel Predefined Config

The ToolPanel Predefined Config has 2 collections:

PropertyDescriptionDefault
ModuleButtonsAdapTable Module Buttons visible in ToolPanelEmpty Array
ToolPanelsToolPanels visibleToolPanels for all available Modules (subject to Entitlement rules)

ToolPanel Options

There are a few properties available in ToolPanel Options to configure ToolPanel behaviour

PropertyDescriptionDefault
adaptableToolPanelTitleTitle for AdapTable ToolPanel Component - appears vertically at side'AdapTable'
customToolPanelButtonsToolPanel Buttons provided by Users which perform custom behaviour
customToolPanelsToolPanels provided by Users which contain custom content
iconKeyKey of icon to be used (beside the label) for Adaptable ToolPanel Component'menu'
maxWidthThe max width of AdapTable ToolPanelundefined
minWidthThe min width of AdapTable ToolPanelvar(--ab-cmp-toolpanel__width)
showAdaptableToolPanelDisplays Adaptable ToolPanel Component (only if AG Grid Sidebar is provided)true
showColumnsDropdownDisplay the Columns dropdowntrue
showModulesDropdownDisplay the Modules dropdowntrue
showToolPanelsDropdownDisplay the Tool Panels dropdowntrue
toolPanelOrderOrder of displayed ToolPanels in Sidebar['filters', 'columns', 'AdaptableToolPanel']
widthThe initial width of AdapTable ToolPanelvar(--ab-cmp-toolpanel__width)

ToolPanel API

This section of the Adaptable API has just a few functions:

MethodDescription
closeAdapTableToolPanel()Closes the Tool Panel section (irrespective of which toolpanel is showing)
getCustomToolPanelButtons()Retrieves all Custom Tool Panel Buttons defined in ToolPanelOptions
getCustomToolPanelByName(name)Retrieves the CustomToolPanel with the given name (or undefined if no match is found)
getCustomToolPanels()Retrieves all Custom Tool Panels defined in ToolPanelOptions
getToolPanelState()Retrieves Tool Panel section from Tool Panel State
openAdapTableToolPanel()Opens the Adaptable ToolPanel Component
setAdaptableToolPanelVisibilityMode(adaptableToolPanel, visibilityMode)Sets the given Adaptable ToolPanel with the provided visibilityMode (expanded / collapsed)
setCustomToolPanelVisibilityMode(customToolPanelName, visibilityMode)Sets the Custom ToolPanel with the given name with the provided visibilityMode (expanded / collapsed)
showToolPanelPopup(popupParams)Opens the Tool Panel popup