AdapTable Version:

Framework:

Alert Notification

Summary

AdapTable Alerts can be configured to display a Notification when triggered
The Notification can be configured to display an AdapTable Form which can be one of 2 types:
- fully defined form with a full range of controls (can include multiple inputs, buttons and other UI controls)
- reduced form with Alert Command Buttons which are wired up to System (and Custom) Alert Commands

A very common Alert Behaviour is to display a Toast Notification whenever the Alert fires.

Hint

This is done by setting DisplayNotification to true in the AlertProperties section of the Alert Definition

By default the Notification will display the Alert's Message - the Header and Text that describe the Alert.

Find Out More

See Alert Message for instructions on the different ways this Message can be provided

Alternatively, the Notification can be configured, instead, to show an Adaptable Form.

This Alert Form can be configured to render 2 different sets of content

a set of Alert Buttons - each with an associated Alert Command
a fully featured Alert Form (including any UI controls that are required)

Alert Command Buttons

The Alert Notification can be configured to show a set of Alert Command Buttons.

Alert Command Buttons are highly-configurable Adaptable Buttons, with many properties available, e.g. for managing style, visibility, and enabled status.

Note

If using OpenFin or interop.io Plugins, these buttons will display with other Notifications shown by those containers

Each Button has an, additional, Actions property - which can contain an array of Alert Button Actions.

As the name implies, these actions will do something when the Button is clicked.

Hint

AdapTable will automatically wire up these Actions to the onClick of the Button

There are 2 types of Alert Command Buttons:

System Command Buttons - shipped by AdapTable for the most common use cases (so far 7 are available)
Custom Command Buttons - provided by developers to deal with bespoke requirements

Caution

Alert Commands differ to Alert Behaviours as the latter trigger when the Alert itself is fired
However Alert Commands trigger when a Button in an Alert Form is clicked

Alert Command Buttons can be provided by:

developers using Alert Initial State (via the AlertForm property of the Alert Definition)
by run-time users in the Notification section of the Alert Wizard

Caution

Alerts created by end users at run-time can only contain Command Buttons (and not fully-featured Alert Forms)

System Alert Button Actions

AdapTable provides 7 Alert Commands, selectable by end-users when creating an Alert in the AdapTable UI:

highlight-cell
highlight-row
jump-to-cell
jump-to-row
jump-to-column
suspend
undo

Hint

The suspend Action essentially sets the IsSuspended property in the Alert Definition to true

System Alert Command Buttons

Fork Fork

This demo fires an Alert when any value in Github Stars column is changed
It displays a Notification with 2 Buttons that are attached to System Alert Commands:
- Show Me - is wired up to 2 Commands: highlight-cell and jump-to-cell
- Undo - triggers 1 Command: undo

Try It Out

Edit a cell in the Github Stars Column and see the Alert with 2 Actions. Click 'Notify' to see the System Status message which is sent

Custom Alert Button Actions

In addition to the Alert Commands provided by AdapTable, developers can supply their own Commands.

This is done via the commandHandlers property in Alert Options.

Note

Custom Alert Commands can then be referenced in Alert Initial State, where they can be "wired up" to Alert Buttons
Additionally AdapTable will display them in the Notifications step in the Alert Wizard to assist run-time users

commandHandlers

CommandHandler[]

Custom onClick Handlers for Buttons (displayed in Alert Notifications)

CommandHandler[]

Provided by developers to supplement the System Alert Commands shipped with AdapTable.

The CommandHandler object contains a name property and a handler function, and is defined as follows:

export declare type CommandHandler = {
  name: string;
  handler: (button: AlertButton, context: AlertFormContext) => void;
};

As can be seen the handler function is identical in nature to the Alert Button's onClick - taking the Button and the Alert Context and returning void.

commandHandlers: [
  {
    name: 'email-support',
    handler: (
      button: AdaptableButton<AlertFormContext>,
      context: AlertFormContext
    ) => {
     // Send the Alert details to an Email recipient
    },
  },
],

Custom Alert Command Buttons

Fork Fork

This demo fires an Alert when any value in Github Stars column is changed.
The Alert displays a Notification with a Notify Button which is attached to a Custom (i.e. bespoke) Alert Command email-support
Note: for this impelementation we simply send a System Status Message but a real world implementation would be different

Try It Out

Edit a cell in the Github Stars Column and see the Alert with the 'Notify' Button
Click the Button to see the System Status message which is sent

import {
  AdaptableOptions,
  AlertButton,
  AlertFormContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Alert Action Buttons',
  alertOptions: {
    commandHandlers: [
      {
        name: 'email-support',
        handler: (
          button: AlertButton<AlertFormContext>,
          context: AlertFormContext
        ) => {
          // Normally would email support, here just send System Status Message
          context.adaptableApi.systemStatusApi.setWarningSystemStatus(
            context.alert.header,
            context.alert.message
          );
        },
      },
    ],
  },
  notificationsOptions: {
    duration: 'always',
    position: 'BottomCenter',
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert', 'SystemStatus'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert', 'SystemStatus'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-github-stars',
          MessageType: 'Warning',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: {
            BooleanExpression: 'ANY_CHANGE()',
          },
          AlertProperties: {
            DisplayNotification: true,
          },
          AlertForm: {
            Buttons: [
              {
                Label: 'Notify',
                Command: ['email-support'],
                ButtonStyle: {
                  tone: 'info',
                  variant: 'text',
                },
              },
            ],
          },
        },
      ],
    },
    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,
        },
      ],
    },
  },
};

Alert Forms

The Alert Notification can be configured, instead, to render a full Alert Form.

This is a fully-featured, UI-rich Adaptable Form, containing multiple inputs and controls (with validation).

An Alert Form can only be configured by developers at design-time, and requires a 2-step process:

The Form is configured in full in the alertForms section of Alert Options
The Form is referenced by name in the AlertForm property of the Alert Definition in Alert Initial State

Find Out More

The Adaptable Form Guide has full instructions on configuring dynamic Forms with multiple inputs and validation

alertForms

AlertForm[]

Fully configured Forms to show in Alert Notifications

AlertForm[]

Alert Notifications can contain Adaptable Forms with multiple inputs and buttons.

alertForms: [
  {
    name: 'setStars',
    form: {
      fields: [
        {
          fieldType: 'number',
          label: 'Stars',
          name: 'github_stars',
        },
      ],
      buttons: [
      {
        label: 'Set',
        disabled: (_button, context) => {
          if (!context.formData?.github_stars) {
            return true;
          }
          const value = Number(context.formData?.github_stars);
          return value <= 0 || isNaN(value);
        },
        onClick: (_button, context) => {
          if (context.alert.alertType == 'cellChanged') {
            const cellChangedAlert = context.alert as AdaptableCellChangedAlert;
            const cellChangedInfo = cellChangedAlert.cellDataChangedInfo;
            const cellUpdateRequest: CellUpdateRequest = {
              columnId: cellChangedInfo.column.columnId,
              newValue: Number(context.formData?.github_stars),
              primaryKeyValue: cellChangedInfo?.primaryKeyValue,
              rowNode: cellChangedInfo?.rowNode,
            };
            context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
          }
        },
      },
      {
        label: 'Cancel',
        buttonStyle: {
          tone: 'neutral',
          variant: 'raised',
        },
        onClick: (_button, context) => {
          if (context.alert.alertType == 'cellChanged') {
            const cellChangedAlert = context.alert as AdaptableCellChangedAlert;
            const cellChangedInfo = cellChangedAlert.cellDataChangedInfo;
            const cellUpdateRequest: CellUpdateRequest = {
              columnId: 'github_stars',
              newValue: cellChangedInfo?.oldValue,
              primaryKeyValue: cellChangedInfo?.primaryKeyValue,
              rowNode: cellChangedInfo?.rowNode,
            };
            context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
          }
        },
      },
    ],
    },
  },
],

Adaptable Forms in Alerts

Fork Fork

This demo displays an Alert Form when a cell in Github Stars column is given a negative value
The Form contains 3 elements:
- a numeric input which will receive the new value for the Cell
- a Set button - which will replace the 0 in the Cell with the value provided in the input
- a Cancel Button - which will revert the Cell to its initial value

Try It Out

Set a GitHub Stars cell to a negative value and see the Alert Form appear with the input and the 2 buttons
Provide a new value and click 'Set' and note how the cell updates
Click 'Cancel' and note how the cell reverts to the initial value

import {
  AdaptableCellChangedAlert,
  AdaptableOptions,
  CellDataChangedInfo,
  CellUpdateRequest,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Alert Form',
  notificationsOptions: {
    // this can be a number (duration in millis) or the string 'always'
    duration: 'always',
  },
  alertOptions: {
    alertForms: [
      {
        name: 'setStars',
        form: {
          fields: [
            {
              fieldType: 'number',
              label: 'Stars',
              name: 'github_stars',
            },
          ],
          buttons: [
            {
              label: 'Set',
              disabled: (_button, context) => {
                if (!context.formData?.github_stars) {
                  return true;
                }
                const value = Number(context.formData?.github_stars);
                return value <= 0 || isNaN(value);
              },
              onClick: (_button, context) => {
                if (context.alert.alertType == 'cellChanged') {
                  const cellChangedAlert =
                    context.alert as AdaptableCellChangedAlert;
                  const cellChangedInfo = cellChangedAlert.cellDataChangedInfo;
                  const cellUpdateRequest: CellUpdateRequest = {
                    columnId: cellChangedInfo.column.columnId,
                    newValue: Number(context.formData?.github_stars),
                    primaryKeyValue: cellChangedInfo?.primaryKeyValue,
                    rowNode: cellChangedInfo?.rowNode,
                  };
                  context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
                }
              },
            },
            {
              label: 'Cancel',
              buttonStyle: {
                tone: 'neutral',
                variant: 'raised',
              },
              onClick: (_button, context) => {
                if (context.alert.alertType == 'cellChanged') {
                  const cellChangedAlert: AdaptableCellChangedAlert =
                    context.alert as AdaptableCellChangedAlert;
                  const cellChangedInfo = cellChangedAlert.cellDataChangedInfo;
                  const cellUpdateRequest: CellUpdateRequest = {
                    columnId: 'github_stars',
                    newValue: cellChangedInfo?.oldValue,
                    primaryKeyValue: cellChangedInfo?.primaryKeyValue,
                    rowNode: cellChangedInfo?.rowNode,
                  };
                  context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
                }
              },
            },
          ],
        },
      },
    ],
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-github-stars',
          MessageType: 'Warning',
          MessageHeader: 'Github Stars Cannot be Negative',
          MessageText:
            'Provide a new value for Github Stars, or click "Cancel" to undo',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Negative',
              },
            ],
          },
          AlertProperties: {
            DisplayNotification: true,
            HighlightCell: true,
          },
          AlertForm: 'setStars',
        },
      ],
    },
    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,
        },
      ],
    },
  },
};

PreviousValidation Alerts NextAlert Message