Dashboard

The Dashboard - usually placed above the Grid - is designed to provide quick access to commonly required AdapTable functionality.

It contains buttons, tabs, toolbars and Quick Search and more and isfully configurable both at design-time (through Predefined Config) and at run-time through config screens.

It comprises 2 sections:

  • Dashboard Header: contains the Modules Dropdown, Module Buttons, Custom Buttons and Quick Search
  • Dashboard Tabs: named groups of Toolbars
important

Everything in the Dashboard is highly customisable either at design-time through Dashboard Predefined Config or at run-time through the UI

tip

As well as Buttons and Toolbars provided by AdapTable you can create Custom Toolbars and Custom Buttons

Dashboard Contents

The Dashboard contains the following elements:

Modules Menu

A dropdown on the left hand side of the Dashboard Header that shows a list of all AdapTable Modules to which the user has a valid Entitlement. Clicking a menu entry will open the popup associated with that Module.

tip

The Modules Menu can be hidden via the showModulesDropdown property of Dashboard Options.

const dashboardOptions: DashboardOptions = {
showModulesDropdown: false
};

Tabs and Toolbars

Tabs are named collections of Toolbars - either supplied Module Toolbars or Custom created ones.

note

If no Tabs are present in Predefined Config, AdapTable will create a default Tab.

Module Toolbars are essentially collections of controls which provide quick, easy access to a single Module (e.g. the Export Toolbar contains a dropdown showing all Reports together with add / edit / delete buttons).

Each Module Toolbar has these elements:

  • Controls relevant to that Module
  • Name of the Module
  • A configure button which opens the Module's Popup
  • A close button which removes the Toolbar from the Tab (disabled if Dashboard Entitlement is 'ReadOnly')

AdapTable currently provides these Module Toolbars:

Additionally these Module Toolbars are available if the appropriate plugin is loaded:

const demoConfig: PredefinedConfig = {
Dashboard: {
Tabs: [
{
Name: 'Search',
Toolbars: ['QuickSearch', 'DataSource', 'Query'],
},
{
Name: 'Edit',
Toolbars: ['BulkUpdate','SmartEdit'],
},
{
Name: 'Grid',
Toolbars: ['Layout', 'CellSummary', 'SystemStatus']
},
],
}
};

Default Tab

If there are no Tabs are present in Predefined Config, AdapTable will create a default Tab.

The Tab is named 'Toolbars' and (depending on the user's Entitlements) contains the Query, Layout, Export & Filter Toolbars.

tip

To prevent the default Tab being created provide a Tabs collection (or an empty array to set no Toolbars)

const demoConfig: PredefinedConfig = {
Dashboard: {
Tabs: [],
}
};

Custom Buttons

A group of custom Adaptable Buttons which will appear in the Dashboard Header.

caution

This list is set via the customDashboardButtons property of Dashboard Options, NOT in Dashboard Config

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
tip

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 DashboardButtonContext object defined as follows:

PropertyDescription
dashboardStateCurrent Dashboard State
const adaptableOptions: AdaptableOptions = {
dashboardOptions: {
customDashboardButtons: [
{
label: 'First',
buttonStyle: (button: AdaptableButton<DashboardButtonContext>, context: DashboardButtonContext) => {
return context.dashboardState.ActiveTabIndex == 0
? {
variant: 'raised',
tone: 'info',
}
: {
variant: 'outlined',
tone: 'success',
};
},
icon: {
height: 30,
src: 'https://img.icons8.com/ios-glyphs/30/000000/sort.png',
},
onClick: (button: AdaptableButton<DashboardButtonContext>, context: DashboardButtonContext) => {
console.log('button onClick function', { button, context });
},
hidden: (button: AdaptableButton<DashboardButtonContext>, context: DashboardButtonContext) => {
return context.dashboardState.IsCollapsed != true;
},
},
{
label: 'Second',
buttonStyle: {
variant: 'raised',
tone: 'accent',
},
onClick: (button: AdaptableButton<DashboardButtonContext>, context: DashboardButtonContext) => {
console.log('button onClick function', { button, context });
},
},
{
label: 'cb3',
buttonStyle: {
variant: 'raised',
tone: 'accent',
},
icon: {
height: 20,
src: 'https://img.icons8.com/ios-glyphs/30/000000/sort.png',
},
onClick: (button: AdaptableButton<DashboardButtonContext>, context: DashboardButtonContext) => {
console.log('button onClick function', { button, context });
},
},
]
}
},

Module Buttons

A group of 'shortcut' buttons which each open the popup associated with that Module.

note

This list can be set via the ModuleButtons property of Dashboard State.

const demoConfig: PredefinedConfig = {
Dashboard: {
ModuleButtons: ['BulkUpdate', 'SmartEdit', 'ConditionalStyle', 'FormatColumn'],
}
};

Quick Search

A simple text search across all visible columns (using the Quick Search Module)

tip

This can be hidden by setting showQuickSearchInHeader in Dashboard Options to false.

adaptableOptions.dashboardOptions = {
showQuickSearchInHeader: false,
};

Application Icon

The Dashboard can display an Application Icon in the top left corner of the Dashboard.

This is provided by the applicationIcon property of User Interface Options which is of type AdaptableIcon.

adaptableOptions.userInterfaceOptions = {
applicationIcon: {
src: 'https://docs.adaptabletools.com/img/favicon_white.png',
height: 20,
width: 20
},
};

Custom Toolbars

In addition to the Toolbars shipped by AdapTable, users can create their own Custom Toolbars through the customToolbar property in Dashboard Options.

note

Once created, they are treated as full toolbars and can be placed in any Tab as required.

The full definition is as follows:

PropertyDescription
frameworkComponentThe Framework-specific (Angular or React) component to be rendered
nameHow Toolbar is referenced (e.g. in Dashboard Popup when managing toolbars)
renderFunction to provide custom content when NOT using a Framework wrapper
showCloseButtonShows a Close button at the bottom of Custom Toolbar
showConfigureButtonShows a Configure (wrench) button which when clicked fires CustomToolbarConfigured event
titleTitle to display in Toolbar; if unset or empty string, nothing will show
toolbarButtonsOptional set of buttons to show in the Toolbar

You can provide 2 sets of content to a Custom Toolbar:

  1. A list of Adaptable Buttons
  2. Bespoke content (when more than buttons are required)
important

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

Providing AdapTable Buttons

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

tip

If you require just to display a few buttons in the Custom Toolbar 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 CustomToolbarButtonContext object defined as follows:

PropertyDescription
customToolbarCustom Toolbar which hosts the Button
dashboardStateCurrent Dashboard State

Custom Toolbar Buttons Example

const adaptableOptions: AdaptableOptions = {
dashboardOptions: {
customToolbars: [
{
name: 'Toolbar1',
showConfigureButton: true,
showCloseButton: true,
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',
showConfigureButton: true,
showCloseButton: true,
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
},
},
]
},
],
},
};

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 property is used when using AdapTable core and not one of the Framewwork Wrappers

tip

See Custom Toolbars in React Wrapper or Custom Toolbars in Angular Wrapper for details on how to provide custom toolbar content if 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 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.

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

Framework Components

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

You need to populate the frameworkComponent property of Custom Toolbar.

This can be one of 2 types:

Configuring Custom Toolbars

Like all Toolbars, Custom Toolbars can be configured.

If the showConfigureButton property in the Custom Toolbar definition is 'true', then a Configure button is displayed in the toolbar.

When this button is clicked, AdapTable will trigger the CustomToolbarConfigured Event, allowing you to perform any functionality you require.

Closing Custom Toolbars

Like all Toolbars, Custom Toolbars can also be closed.

If the showCloseButton property in the Custom Toolbar definition is 'true', then a Close button is displayed in the toolbar.

When this button is clicked, AdapTable will automatically close (i.e. hide) the toolbar.

caution

If a Custom Toolbar is closed, you will need to go into Dashboard settings to put it back in a Tab

Dashboard UI Settings

AdapTable provides numererous options to allow you to configure and set up the Dashboard to meet your precise requirements.

Inline Mode

By default Adaptable displays the name of each Tab in a row, and beneath that is displayed the contents of each Toolbar (in the active Tab).

An alternative to this is Inline Mode which takes up less screen estate.

When this is set, the Dashboard Header collapses to become the first Toolbar, and a dropdown displays a list of available Tabs.

tip

If there is only one Tab then the dropdown will not be displayed; this is a useful way just to show Toolbars without the User seeing the Tab

const demoConfig: PredefinedConfig = {
Dashboard: {
IsInline: true,
}
};

See the Dashboard Inline Demo.

Collapsed View

This shows just the Dashboard Header with the name of the instance and any buttons but no Toolbars.

tip

To collapse / expand the Dashboard click on a Dashboard tab.

const demoConfig: PredefinedConfig = {
Dashboard: {
IsCollapsed: true
}
};

Floating View

This shows just the Dashboard name in reduced width and it can be dragged to any position by clicking on the Name (the mouse will change to a cross).

note

Floating is only available if canFloat is set to true in Dashboard Options (the default value)

const demoConfig: PredefinedConfig = {
Dashboard: {
CanFloat: true,
IsFloating: true,
}
};
tip

To float / dock the Dashboard double-click the Name in the Dashboard Header

Hidden View

This hides the Dashboard from the user (but it is created and can later be made visible).

note

If you want to remove the Dashboard completely so that it cannot be made visible in any circumstances then set 'Dashboard' to hidden in Entitlements

const demoConfig: PredefinedConfig = {
Dashboard: {
IsHidden: true,
}
};
tip

A hidden Dashboard can be made visible via the Column Header Menu, the Toolpanel or Dashboard Api.

Wrapping Toolbars

By default all Toolbars (in the Active Tab) are shown in a big horitzonal row.

This means that if they took up more space than the grid or enclosing window, scrolling is required to see those to the right.

One alternative option is to wrap the Toolbars - which is controlled by the '--ab-dashboard-wrap' CSS Variable

The default value is nowrap:

--ab-dashboard-wrap: nowrap

So to wrap the toolbars in the Dashboard set it to wrap:

--ab-dashboard-wrap: wrap
tip

Another relevant CSS Variable property is '--ab-dashboard-gap-size' which controls the gap between Dashboard Toolbars as follows:

--ab-dashboard-gap-size: 2px

Dashboard Title

By default the title shown in the middle of the Dashboard will use the value of the adaptableId property in Adaptable Options.

This can be changed by explicitly setting the DashboardTitle property in Dashboard Config

Dashboard Predefined Config

PropertyDescriptionDefault
ActiveTabIndexThe index of the Active Tab (in Tabs collection)
DashboardTitleTitle to display in Dashboard Header; if missing, 'adaptableId' property in Adaptable Options is usedadaptableId in Adaptable Options
FloatingPositionPosition of Dashboard in 'floating mode' - set and stored by AdapTable
IsCollapsedWhether Dashboard is collapsed; if true, header is visible (but not tabs' contents)false
IsFloatingWhether Dashboard is floating; if true, appears in draggable, minmised form (double-click to revert to default position)false
IsHiddenWhether Dashboard is completely hidden - can be made visible again in Column menu and toolpanelfalse
IsInlineAlternative way of showing Expanded Dashboard where headers section is to left of Toolbarsfalse
ModuleButtonsModule Buttons visible in Dasbhoard Header when application loads - open popup screen for associated AdapTable Module['SystemStatus', 'GridInfo', 'Layout' 'ConditionalStyle']
TabsNamed group of Toolbars - each Toolbar should only be in one Tab; if no Tabs are provided, AdapTable creates one named 'Toolbars'

In this example we have:

  • created 3 Dashboard Tabs ('Search', 'Edit' and 'Grid') each with their own Toolbars
  • created a Custom Toolbar ('appToolbar') and put it in the 'Grid' Tab (and defined it in Dashboard Options)
  • set 4 Module Buttons to be visible ('GridInfo', 'SystemStatus', 'SmartEdit' and 'FormatColumn')
const adaptableOptions: AdaptableOptions = {
dashboardOptions: {
customToolbars: [
{
name: 'appToolbar',
showConfigureButton: true,
showCloseButton: true,
},
]
},
predefinedConfig: {
Dashboard: {
IsInline: true,
ModuleButtons: ['GridInfo', 'SystemStatus', 'SmartEdit', 'FormatColumn'],
Tabs: [
{
Name: 'Search',
Toolbars: ['QuickSearch', 'DataSource', 'Query'],
},
{
Name: 'Edit',
Toolbars: ['BulkUpdate','SmartEdit'],
},
{
Name: 'Grid',
Toolbars: ['Layout', 'CellSummary', 'SystemStatus', 'appToolbar']
},
],
}
}

Dashboard Options

The Dashboard Options section of Adaptable Options includes some useful properties including:

PropertyDescriptionDefault
canFloatWhether the Dashboard can be floated; if true (the default), double-clicking Dashboard puts it in float modetrue
customDashboardButtonsCustom Adaptable Buttons to appear in top corner of Dashboard - next to Module Buttons
customToolbarsToolbars provided by Users which contain custom content
showModulesDropdownShows Modules dropdown in Dashboard Header (the 'home' icon); each item connects to an AdapTable Module, opening its popup screentrue
showQuickSearchInHeaderShows Quick Search textbox in the Dashboard Header; the UI component is still subject to the QuickSearch Entitlementstrue

Events

There are 2 Adaptable Event which are fired by the Dashboard to cater for different scenarios:

Dashboard Changed

This is fired whenever anything changes in Dashboard State.

It contains a DashboardChangedInfo object:

PropertyDescription
actionNameWhat caused Dashboard State to change
newDashboardStateCurrent Dashboard State
oldDashboardStatePrevious Dashboard State

Custom Toolbar Configured

This is fired when the Configure button is clicked in a Custom Toolbar.

It contains a CustomToolbarConfiguredInfo object:

PropertyDescription
customToolbarCustom Toolbar in which the 'Configure' button has been clicked

Events Subscription

Subscribing to the Events is done the same as with all Adaptable Events:

api.eventApi.on('DashboardChanged', (eventInfo: DashboardChangedInfo) => {
// do something with the info
});
api.eventApi.on('CustomToolbarConfigured', (eventInfo: CustomToolbarConfiguredInfo) => {
// do something with the info
});

Managing the Dashboard

There are 3 main ways to manage the Dashboard:

Dashboard Config Screen

The Dashboard Configuration screen is a Popup with 2 tabs:

tip

The Popup can be opened via the Modules Menu or the Configure Dashboard option in the Column Menu

Tool Panel

The Dashboard Tool Panel contains 3 checkboxes:

Modules Menu

The Modules Menu and each Column Menu has a 'Dashboard' menu entry with 4 sub menu items:

UI Entitlements

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

The ReadOnly Entitlement behaviour is that the Dashboard cannot be configured and individual Toolbars cannot be closed or re-ordered.

note

With a ReadOnly Entitlement the Dashboard visibility mode can still be changed (e.g. the Dashboard can be expanded / hidden / floated etc.)

Dashboard API

MethodDescription
addCustomToolbarButtons(customToolbarName, buttons)Adds Toolbar Buttons to current collection in Custom Toolbar
clearCustomToolbarButtons(customToolbarName)Clears all Toolbar Buttons from Custom Toolbar
collapseDashboard()Collapses Dashboard so only Dashboard Header is visible (and not Toolbars' contents)
dockDashboard()Docks Dashboard so it 'snaps back' into its customary position above the grid
expandDashboard()Expands Dashboard so Toolbars in Active Tab are fully visible
fireDashboardChangedEvent(trigger, oldSate, newState)Fires Dashboard Changed Event
floatDashboard()Floats Dashboard so only Dashboard Header is visible (in reduced size); can be dragged to a new location
getActiveTab()Returns current Active Tab (if there is one)
getActiveTabIndex()Returns current Active Tab index (if there is one)
getCurrentToolbars()Retrieves all Toolbars in Active Tab
getCustomDashboardButtonByLabel(buttonLabel)Retrieves first Custom Button with given Label
getCustomDashboardButtons()Retrieves all Custom Buttons
getCustomToolbarByName(customToolbarName)Returns Custom Toolbar with the given name
getCustomToolbarContentsDiv(customToolbarName)Returns 'div' element for given Custom Toolbar
getCustomToolbars()Retrieves all Custom Toolbars
getDashboardState()Retrieves Dashboard section from Adaptable State
getTabByName(tabName)Retrieves the Tab from State that matches inputted name
hasCustomToolbarChanged(dashboardChangedInfo, customToolbarName)Has a custom toolbar become visible or
hideDashboard()Hides the Dashboard so cannot be seen
isDashboardCollapsed()Is Dashboard Collapsed
isDashboardDocked()Is Dashboard Docked
isDashboardExpanded()Is Dashboard Expanded
isDashboardFloating()Is Dashboard Floating
isDashboardHidden()Is Dashboard Hidden
isDashboardVisible()Is Dashboard Visible
isToolbarVisible(toolbar)Checks if a given Toolbar is visible
setActiveTab(tabName)Sets Active Tab in Dashboard
setActiveTabIndex(tabIndex)Sets Active Tab in Dashboard
setCustomToolbarButtons(customToolbarName, buttons)Replaces Toolbar Buttons in Custom Toolbar with the new set
setCustomToolbarContents(customToolbarName, contents)Populates a Custom Toolbar with content
setDashboardTitle(title)Sets title of Dashboard Header
setModuleButtons(moduleButtons)Sets which Module Buttons are visible
showDashboard()Makes the Dashboard visible
showDashboardPopup()Opens the Dashboard popup screen

FAQ

Is there a limit to the amount of Module buttons that I can show?

No, you can choose to show as many as you want.

Can I hide the Modules dropdown?

Yes, via the showModulesDropdown property of Dashboard Options

Can I add my own content to the Dashboard?

Yes, the customToolbars property in Dashboard Options serves precisely this purpose.

Why do I see a tab called 'Toolbars'?

This is added automatically by AdapTable if you do not provide any Toolbars and do not spefically set empty.

AdapTable creates a new Tab which contains the default set of Toolbars.

This Tab can be later replaced either in the UI, or in Predefined Config by setting a Revision Number.

Is there a way to see just the Toolbars without creating a Tab?

Not in the standard Expanded mode. However if you set the Inline Mode and you only have one Tab, the Tab selector dropdown will be hidden.

Can I prevent my users from moving toolbars and tabs around?

Yes, set the Entitlement accessLevel to ReadOnly

More Information