Adaptable Button

Adaptable Buttons are used widely in AdapTable whenever a button is required including:

It can be styled to user requirements and contains useful function hooks to allow control over how and when it appears and what happens when it is clicked.

The Adaptable Button object is 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
important

For some Form use cases (e.g. Alerts) AdapTable will make sure that at least one 'OK' button is shown (which will close the Form)

Button Properties

An AdapTable Button contains 7 optional properties that can be provided as required.

note

Some of these properties return a value, while others return a function will be invoked by AdapTable when required to return the value; others can return either a value or a function

The function always receives the same 2 parameters when invoked (and returns an appropriate value):

onClick

The function which is called when the Button is clicked and returns void:

onClick?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void;
tip

Although not mandatory, this function should nearly always be provided in practice

label

The text to show as the Button's caption.

The property can return either a string or a function which returns a string:

label?: string |
(((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string);
note

If this property returns the string itself then no function will be invoked

buttonStyle

Provides the Button Style for the Button.

The property can return either a ButtonStyle object or a function which returns a ButtonStyle:

buttonStyle?: ButtonStyle |
((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => ButtonStyle);
note

If this property returns the Button Style object itself then no function will be invoked

toolTip

The text to use as the Button's Tooltip.

The property can return either a string or a function which returns a string:

toolTip?: string |
((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string);
note

If this property returns the string itself then no function will be invoked

hidden

Function that returns whether or not the Button will display.

important

If this property is not provided the Button will be displayed

The function is invoked when the Button is about to be rendered - allowing you to decide whether or not it should display - and returns a boolean:

hidden?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean;

disabled

Function that disables / enables the button based on its evaluation result:

disabled?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean;

icon

This property returns an icon to display for the button.

important

This is the only Button property which only returns a value and doesn't contain a function option

The property returns an AdaptableIcon object which is defined as follows:

PropertyDescription
cssPropertiesCSS Properties
srcurl specifying where icon can be found (mandatory)
styleThe style for the icon - has height and width properties
caution

The src property is mandatory but other properties are optional

note

If the style property is not provided, AdapTable will use default values for height and width of 20px

tip

Use --ab-cmp-simple-button__height and --ab-cmp-simple-button__width CSS Variables to change these default vlaues

Button Style

AdapTable provides a ButtonStyle object which defines how a Button will be visually rendered.

The object has 3 properties:

PropertyDescriptionDefault
classNameCSS Classname to use for the Button
toneButton's Tone - values: 'success', 'error', 'neutral', 'none', 'warning', 'info', 'accent''neutral'
variantHow Button appears - values: 'text', 'outlined', 'raised''outlined'

Tone

The tone provides the colour for the button using the theme's CSS Variables. The options are:

Tone ValueCSS Variable
success--ab-color-success
error--ab-color-error
neutral--ab-color-text-on-primary
noneinherit
warning--ab-color-warn
info--ab-color-info
accent--ab-color-text-on-secondary

Variant

The variant property specifies how the Button will appear and has 3 options:

Variant ValueBehaviour
textDisplays the caption
outlinedProvides a border
raisedAccentuates the button

Button Contexts

All the functions that the Button can recieve, include a Context parameter.

Each implementation of the Adaptable Button in AdapTable will use its own, bespoke, context property that contains information relevant to that particular use case.

important

In addition the button argument is of type of the same Context

button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE

There are 7 Context Types - for 7 different use cases:

Action Column

When using a button in an Action Column the handler receives an ActionColumnButtonContext object which is defined as follows:

PropertyDescription
actionColumnAction Column in question
primaryKeyValuePrimary Key Value in current row
rowNodeCurrent Row Node

Example

const adaptableOptions: AdaptableOptions = {
userInterfaceOptions: {
actionColumns: [
{
columnId: 'Action',
includeGroupedRows: true,
actionColumnButton: {
label: 'Triple',
onClick: (button: AdaptableButton<ActionColumnButtonContext>,
context: ActionColumnButtonContext) => {
const notional = context.rowNode.data['notional'];
const newNotional = notional * 3
const pkValue = adaptableApi.gridApi.getPrimaryKeyValueForRowNode(context.rowNode);
adaptableApi.gridApi.setCellValue('notional', newNotional, pkValue, true);
},
hidden: (button: AdaptableButton<ActionColumnButtonContext>,
context: ActionColumnButtonContext) => {
return context.rowNode.data?.currency != 'USD';
},
buttonStyle: {
variant: 'raised',
tone: 'accent',
},
},
},
],
},
}

Alert

When using a button in an Alert form the handler receives an AlertButtonContext object which is defined as follows:

PropertyDescription
alertAlert that has been triggered
formDataData in the Alert Form

Example

const adaptableOptions: AdaptableOptions = {
alertOptions: {
alertForms: [
{
name: 'Overwrite Form',
form: {
description: 'Please enter a value < 30 or click "Undo" ',
fields: [
{
name: 'ItemCount',
label: 'Item Count',
defaultValue: '',
fieldType: 'number',
},
],
buttons: [
{
label: 'Overwrite',
disabled: (button: AdaptableButton<AlertButtonContext>,
context: AlertButtonContext) => {
const newValue: any = context.formData?.['ItemCount'];
return (
!newValue || newValue < 0 || newValue > 30
);
},
onClick: (button: AdaptableButton<AlertButtonContext>,
context: AlertButtonContext) => {
const columnId = context.alert.dataChangedInfo?.columnId;
const primaryKeyValue = context.alert.dataChangedInfo?.primaryKeyValue;
const newValue = context.formData?.['ItemCount'];
if (columnId && primaryKeyValue && newValue) {
adaptableApi.gridApi.setCellValue(
columnId,
newValue,
primaryKeyValue,
false
);
}
},
buttonStyle: {
tone: 'warning',
variant: 'outlined',
},
},
{
label: 'Undo',
onClick: (button: AdaptableButton<AlertButtonContext>,
context: AlertButtonContext) => {
if (context.alert?.dataChangedInfo) {
adaptableApi.gridApi.undoCellEdit(
context.alert.dataChangedInfo
);
}
},
buttonStyle: {
tone: 'neutral',
variant: 'outlined',
},
},
],
},
},
],
},
};

Export

When using a button in an Custom Destination form the handler receives an ExportButtonContext object which is defined as follows:

PropertyDescription
customDestinationCustom Export destination
formDataAdaptable Form Data
reportThe exported report
reportDataThe data in the report

Example

const adaptableOptions: AdaptableOptions = {
exportOptions: {
customDestinations: [
{
name: 'Email',
form: {
title: 'Email Settings',
description: 'Provide email subject ',
fields: [
{
name: 'subject',
label: 'Email Subject',
fieldType: 'text',
defaultValue: 'AdapTable Report Data',
},
],
buttons: [
{
label: 'Cancel',
},
{
label: 'Export',
buttonStyle: {
tone: 'success',
variant: 'raised',
},
validate: (button: AdaptableButton<ExportButtonContext>,
context: ExportButtonContext) => {
const subject: any = context.formData?.['subject'];
return subject!= ''
},
onClick: (button: AdaptableButton<ExportButtonContext>,
context: ExportButtonContext) => {
// send the report to an email address
// the context contains the report data
},
},
],
},
},
],
}
},

Dashboard

When showing a DashboardButton the handler receives an DashboardButtonContext object defined as follows:

PropertyDescription
dashboardStateCurrent Dashboard State

Example

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',
};
},
onClick: (button: AdaptableButton<DashboardButtonContext>,
context: DashboardButtonContext) => {
console.log('button onClick function', { button, context });
},
hidden: (button: AdaptableButton<DashboardButtonContext>,
context: DashboardButtonContext) => {
return context.dashboardState.IsCollapsed != true;
},
},
]
}
},

Custom Toolbar

When rendering a Custom Toolbar Button the handler receives an CustomToolbarButtonContext object defined as follows:

PropertyDescription
customToolbarCustom Toolbar which hosts the Button
dashboardStateCurrent Dashboard State

Example

const adaptableOptions: AdaptableOptions = {
dashboardOptions: {
customToolbarButtons: [
{
label: 'First Toolbar btn',
buttonStyle: {
variant: 'text',
tone: 'success',
},
icon: {
src: 'https://img.icons8.com/glyph-neue/64/000000/zoom-in.png',
},
onClick: (button: AdaptableButton<CustomToolbarButtonContext>,
context: CustomToolbarButtonContext) => {
console.log('button onClick function', { button, context });
},
hidden: (button: AdaptableButton<CustomToolbarButtonContext>,
context: CustomToolbarButtonContext) => {
return context.customToolbar.Name != 'Toolbar1';
},
},
],
}
},

ToolPanel

When showing a ToolPanel Button the handler receives an ToolPanelButtonContext object defined as follows:

PropertyDescription
toolPanelStateCurrent ToolPanel State

Example

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,
}
)
);
},
},
],
},
},

Custom ToolPanel

When showing a button in a Custom ToolPanel the handler receives an CustomToolPanelButtonContext object defined as follows:

PropertyDescription
customToolPanelThe Custom ToolPanel which contains the button
toolPanelStateCurrent ToolPanel State

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
},
},
]
},
],
},
};