Alerts Technical Reference
Summary
- Alerts are configured i the Alert section of Adaptable State
- Alert Options contains many properties to enable fine-tuned configuring of Alerts
- Run-time access to Alerts is primarily available through Alert API
- The Alert Fired event is published every time an Alert is fired in AdapTable
Alert State
The Alert section of Adaptable State contains a collection of AlertDefinition objects:
| Property | Type | Description |
|---|---|---|
| AlertDefinitions | AlertDefinition[] | Alert Definitions - will trigger Alerts when rule is met |
Each Alert Definition can be one of two types:
- RuleBasedAlertDefinition
- ScheduledAlertDefinition
Base Properties
Both inherit from Alert Definition Base which is defined as follows:
| Property | Type | Description |
|---|---|---|
| MessageHeader | string | Title of displayed Alert Message |
| MessageText | string | Title of displayed Alert Message; if null, AdapTable creates dynamically using Rule & Scope |
| MessageType | AdaptableMessageType | Type of Alert: 'Info', 'Success', 'Warning', 'Error'; influences Alert colour, icon and logging |
| Name | string | Name of the Alert Definition |
| IsReadOnly | boolean | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') |
| IsSuspended | boolean | Suspends (i.e. turns off) an Adaptable Object |
And both contain an AlertProperties object which derives from Alert Presentation Properties and defines some optional behaviour for the Alert:
| Property | Type | Description |
|---|---|---|
| DisplayNotification | boolean | Displays a notification when Alert is triggered |
| DisplaySystemStatusMessage | boolean | Shows the alert message in the System Status panel |
| LogToConsole | boolean | Logs the Alert message to the console |
| NotificationDuration | NotificationsOptions['duration'] | Notifiction duration(defaults to NotificationOptions.duration) |
| ShowInDiv | boolean | Shows Alert text in the div specificed in alertContainer property of Container Options |
Rule Based Alert Definition
The Rules Based Alert Definition is used for Alerts with Expressions and Scope:
| Property | Type | Description |
|---|---|---|
| AlertForm | string |AlertButtonForm | Form to display in Alert with buttons and inputs |
| AlertProperties | RuleAlertProperties | Properties which set what happens when the Alert is triggered (notification and grid behaviours) |
| Rule | AlertRule | When Alert should be triggered |
| Scope | ColumnScope | Where Alert can be triggered: one, some or all columns or DataTypes |
| IsReadOnly | boolean | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') |
| IsSuspended | boolean | Suspends (i.e. turns off) an Adaptable Object |
And it has these Alert Properties of type RuleAlertProperties defined as follows:
| Property | Type | Description | Default |
|---|---|---|---|
| HighlightCell | boolean |AdaptableStyle | Colours updated Row using MessageType of triggering Alert Definition | |
| HighlightRow | boolean |AdaptableStyle | Colours updated Row using MessageType of triggering Alert Definition | |
| JumpToCell | boolean | Grid will 'jump' to the changed cell which triggered the Alert | |
| JumpToRow | boolean | Grid will 'jump' to the newly added row which triggered the Alert | |
| PreventEdit | boolean | Automatically prevent any cell edit which triggered the Alert (i.e. validation) | false |
Schedule Based Alert Definition
The Schedule Alert Definition is used for Alerts that run on a Schedule:
| Property | Type | Description |
|---|---|---|
| AlertProperties | ScheduledAlertProperties | Notification properties for scheduled alerts (no grid behaviours) |
| Schedule | Schedule | When the alert should run |
| IsReadOnly | boolean | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') |
| IsSuspended | boolean | Suspends (i.e. turns off) an Adaptable Object |
And it has these Alert Properties of type ScheduledAlertProperties defined as follows:
| Property | Type | Description |
|---|---|---|
| IncludeSuspendButton | boolean | When true, the scheduled notification includes a Suspend button |
Alert Options
| Property | Type | Description | Default |
|---|---|---|---|
| alertForms | AlertForm<TData>[] | Full definitions of Alert Forms - the names of which are provided in Alert State | |
| alertMessageHeader | (alertMessageContext:AlertMessageContext<TData>) => string | undefined | Function providing Header to display in Alert; if empty, AdapTable provides dynamically | |
| alertMessageText | (alertMessageContext:AlertMessageContext<TData>) => string | undefined | Function providing Message to display in Alert; if empty, AdapTable provides dynamically | |
| cellHighlightDuration | number | How long (in ms) a Cell will be highlighted when an Alert fires | 2000 |
| commandHandlers | CommandHandler<TData>[] | Custom onClick Handlers for Buttons (displayed in Alert Forms) | |
| dataChangeDetectionPolicy | DataChangeDetectionPolicy | Whether Alert rule is evaluated against the rawValue or formattedValue of the changed cell data | 'rawValue' |
| maxAlertsInStore | number | How many alerts held in State at any one time; when limit is breached, oldest alert will be removed | 20 |
| rowHighlightDuration | number | How long (in ms) a Row will be highlighted when an Alert Fires | 4000 |
| showMissingPrimaryKeyAlert | boolean | Shows Alert if Primary Key column in Adaptable Options is not present or incorrect | false |
| statusbarHighlightDuration | number | How long (in ms) Alert panel in Status Bar highlights when an Alert Fires | 2000 |
Alert API
Full programmatic access to Alerts and related features is available in Alert API.
This enables Alerts to be accessed, created, edited, deleted and shared programmatically.
| Method | Returns | Description |
|---|---|---|
| addAlertDefinition(alertDefinition) | AlertDefinition | Adds given Alert Definition to Adaptable State |
| applyScheduledAlertDefinition(alertDefinition) | void | Fires a scheduled alert definition (notification, system status, etc.) |
| deleteAlertDefinition(alertDefinition) | void | Deletes given Alert Definition from Adaptable State |
| displayAdaptableAlert(alertToShow) | Promise<void> | Displays the given Adaptable Alert |
| displayAdaptableAlertNotification(alert) | void | Displays given Alert as a Toast |
| editAlertDefinition(alertDefinition) | AlertDefinition | Updates given Alert Definition in Adaptable State |
| evaluateAlertDefinitions(alertDefinitions) | void | Evaluates the given Alert Definitions - will fire Alert if rule is met |
| findAlertDefinitions(alertLookupCriteria) | AlertDefinition[] | Find all Alert Definitions which match the given criteria |
| getActiveAlertDefinitions(config) | AlertDefinition[] | Retrieves all Alert Definitions which are currently active |
| getAlertDefinitionById(id, config) | AlertDefinition | Retrieves alert definition by the technical ID (from AlertState) |
| getAlertDefinitionByName(name) | AlertDefinition | undefined | Retrieves an Alert Definition by its Name |
| getAlertDefinitions(config) | AlertDefinition[] | Retrieves all Alert Definitions in Alert State |
| getAlertState() | AlertState | Retrieves Alert section from Adaptable State |
| getSuspendedAlertDefinitions(config) | AlertDefinition[] | Retrieves all Alert Definitions which are currently suspended |
| openAlertSettingsPanel() | void | Opens Settings Panel with Alert section selected and visible |
| showAlert(alertHeader, alertMessage, messageType, alertProperties) | Promise<void> | Creates Alert based on given parameters and displays it. |
| showAlertError(alertHeader, alertMessage) | Promise<void> | Creates an Adaptable Alert based on given parameters and displays it as Error Alert. |
| showAlertInfo(alertHeader, alertMessage) | Promise<void> | Creates an Adaptable Alert based on given parameters and displays it as Info Alert. |
| showAlertSuccess(alertHeader, alertMessage) | Promise<void> | Creates an Adaptable Alert based on given parameters and displays it as Succcess Alert. |
| showAlertWarning(alertHeader, alertMessage) | Promise<void> | Creates an Adaptable Alert based on given parameters and displays it as Warning Alert. |
| suspendAlertDefinition(alertDefinition) | AlertDefinition | Suspends Alert Definition |
| suspendAllAlertDefinition() | void | Suspends all Alert Definitions |
| unSuspendAlertDefinition(alertDefinition) | AlertDefinition | Activates a suspended Alert Definition |
| unSuspendAllAlertDefinition() | void | Activates all suspended Alert Definition |
Alert Fired Event
The Alert Fired Event is published by AdapTable whenever an Alert is fired.