The Alert Module enables the creation of powerful and flexible Alerts.
Alerts are triggered when the Rule specified in an Alert Definition is met, usually as the result of edits or 'ticking' data changes in the Grid.
Alert Definitions can be provided in Alert Predefined Config or created at run-time
The trigger (or Rule) in an Alert Definition can be one of 4 types:
Alerts trigger both as the result of direct user grid edits, and as data ticks in the underlying data source
Most commonly, the Alert Definition will contain a Predicate - the same boolean function as is used as in filters - which has a type (e.g. GreaterThan) and, optionally, inputs (e.g. 100)
Developers can easily provide their own Custom Predicates to create bespoke validation rules.
In more advanced scenarios (e.g. if you want the Alert Definition to react not only to the data change in the cell being edited but look at other values in the row) you can, instead of a Predicate, provide a Boolean Query (i.e. one which returns true/false).
Alert supports Observable Queries - advanced, reative-type Queries, which are triggered as the result of changes (or lack of changes) in a particular row (or set of rows) or in the entire Grid.
For instance, you can trigger an Alert if a particular row has not changed in the last hour, or has changed 5 times in 10 minutes, or if a column / cell value is the highest that its been all day.
Observable Queries require a Scope of 'Whole Row'
See the Observable Expression documentation for more information.
Alerts can also be triggered by Aggregation Queries.
These are Queries which run against aggregated data using a
SUM function, e.g. fire an Alert if the Sum of 'PnL' is > 50M where Currency is Dollar.
Aggregation Queries require a Scope of 'Whole Row'
See the Aggregation Expression documentation for more information.
MessageType of the Alert sets what type of of Message is displayed (and the colour will vary accordingly). The available values are:
Success - (default colour is green)
Info - (default colour is blue)
Warning - (default colour is amber)
Error - (default colour is red)
|DisplayNotification||Displays a notification when Alert is triggered|
|HighlightCell||Colours updated cell using |
|JumpToCell||Grid will 'jump' to the cell which triggered the Alert|
|LogToConsole||Logs the Alert message to the console|
|PreventEdit||Automatically prevent any cell edit which triggered the Alert (i.e. validation) false|
|ShowInDiv||Shows Alert text in the div specificed in |
As can be seen, some of the options for displaying an Alert include:
Display a Notification - useful for important Alerts or where user actions are required
The Notification can additionally include an Adaptable Form - see alert form section below -
and its appearance and behaviour can be heavily customised
Colour the Cell where the data changed that triggered the Alert (based on the Alert's
Unlike a Button Predefined Action, this will automatically happen as soon as the Alert is triggered.
Jump to Cell so that the Grid will immediately show the row which contains the cell that triggered the Alert
Unlike a Button Predefined Action, this will automatically happen as soon as the Alert is triggered.
Show the Alert details in a Div element (that you specify in Container Options)
The previous way of doing this - via
AlertDisplayDivproperty in Alert State - is deprecated
All Alerts when triggered will display (and update the count) in the Alert Toolbar and Alert Tool Panel.
Additionally, all Alerts will fire the AlertFired event (the contents of which will be also sent to the console).
When the Alert is displayed in a Notification there is an option to provide an Adaptable Form inside the Alert.
The Form displays in Notifications triggered by the Alert so make sure
DisplayNotification is set to true in
There are 2 ways to provide an Alert Form
- defining the form in full (including buttons) in Alert Options
- providing a reduced form - with just Buttons and associated actions - in Alert Config
Full Form Definition
The best way to provide a Form to display in an Alert is to follow this 2 step process:
- Define the Adaptable Form in full in the
alertFormssection of Alert Options
- Reference that Form by name in the
AlertFormproperty of the Alert Definition object in Alert Config
This allows you to provide a rich form with Adaptable Buttons that can have multiple function implementations.
In the example below we have defined an Alert which will trigger if 'ItemCount' value is over 30.
This Alert displays a Notification containing a Form (entitled 'Overwrite Form') which includes:
- a numeric field so a new 'Item Count' property
- an overwrite button which enters the new value provided via the form (with validation)
- an undo button which undoes the Cell Edit and reverts to the original value
Form With Actions
Sometimes the full Form provided above might be overkill and you want your form just to include a few buttons with actions and no custom logic for whether they are enabled or visible.
The Form will just contain buttons (which can be styled) and the
onClick will wire to an Alert Action.
Any Alerts created at run-time by the User can only have Action Buttons
AdapTable ships with 5 Alert Actions:
Custom Alert Actions
Developers can easily provide additional Alert Actions at design-time.
These Actions can then be referenced in Config to Alert Buttons (see below)
This is done via the
actionHandlers section of Alert Options.
Each Action Handler is defined as follows:
As can be seen the
handler function is the same as the Alert Button
onClick - taking the Button and the Alert Context and returning void.
In the example below we have defined the same Alert as in the example above - which will trigger if 'ItemCount' value is over 30.
However in this example there is no form with a numeric field and an override button, but we have provided 2 buttons each linked to Actions:
- Show Me: 2 Adaptable actions (highlight-cell, jump-to-cell) and 1 custom action (emailSupport)
- Undo: The undo Adaptable action
Alerts can be used to prevent cell edits from happening when they break the rule set in the Alert Definition.
In this scenario AdapTable will show the Alert before the edit is committed and sent to the server.
This avoids the irritating round-trip scenario where an edit is made which everyone sees and then a second later the value 'jumps back' to how it was previously
To do this set the
PreventEdit property in the Alert Definition to true.
This option was introducted in 8.2 and it replaces the now deprecated, Cell Validation Module as it provides superior functionality and options.
Sometimes the Prevent Edit can be too strong and you might prefer to give users a 'second chance' - i.e. to provide a new value if the initial edit triggers an Alert.
In the example below, we have created an Alert for when 'ItemCost' > 100 and provided a form with:
- a single numeric input and no default value
- a button which overwrites the proposed edited value with the one from the in put, and is disabled if the new value is not betwen 1 and 100
- a button labeled 'undo' which when clicked overwrites the new value (with the old one)
A common scenario in AdapTable is where users want a cell to flash briefly when it changes.
This is performed through Flashing Alerts - with the added advantage that it can be customised to the precise requirements of each user.
In versions of Adaptable prior to Version 9 there were separate Flashing Cell and Updated Row functions that provided this functionality; these have now been merged into Alerts
These can be provided at design time via the
FlashingAlertDefinitions section of Alert Config or at runtime through the UI.
A Flashing Alert extends the standard Alert so it will have Scope and a Rule.
This is typically set to Scope of a single column and a Predicate of 'Any Change' - but Flashing Alerts can be set up to be triggered on any kind of change
It also includes a FlashingAlertProperties object which allows you to define the Up, Down and Neutral change style, the duration and whether a single cell or whole row flashes.
Default flashing alert properties can be set in Alert Options to be used when no properties are provided.
The full object is defined as follows:
|DownChangeStyle||Style for 'Down' value changes|
|FlashDuration||Duration of Flash - can be number (in ms) or 'always'|
|FlashTarget||Should a cell or whole row flash|
|NeutralChangeStyle||Style for 'Neutral' value changes|
|UpChangeStyle||Style for 'Up' value changes|
Set the duration to 'always' if the cell/row should remain coloured until it is explicitly turned off by the user
Doing this will replicate the behaviour of the Updated Row function that was removed in Version 9
The Alert Options section of Adaptable Options contains useful properties for configuring all Alert behaviour.
Alert Options differs governs behaviour across ALL Alerts, (e.g. where Notifications should appear).
Alert Properties, by contrast, defines how Alerts from one particular Alert Definition will behave, e.g. whether to jump to the cell)
Many of the properties set the behaviour of the Toast-style Notification that appears when Alerts are triggered.
An important property is
flashingAlertDefaultProperties which allows you to specify how Flashing Cells should look by default.
You can set default behaviour for Flashing Alerts in Alert Options but still override it for particular Alert Definitions in Alert Config
The full definition is as follows:
|actionHandlers||onClick Handlers for Alert Buttons (defined in Alert State)|
|alertForms||Full definitions of Alert Forms - the names of which are provided in Alert State|
|cellHighlightDuration||How long (in ms) a cell will be highlighted||3000|
|closeWhenClicked||Closes Notification automatically when its clicked||false|
|dataChangeDetectionPolicy||Whether Alert rule should be evaluated against the ||'rawValue'|
|duration||How long (in ms) Notifications display for||3000|
|flashingAlertDefaultProperties||Flashing Alert Defaults||BackColors: Green (up), Red (down), Gray (neutral), Duration: 500ms|
|isDraggable||Can Notification be dragged||false|
|maxAlertsInStore||How many alerts held in State at any one time; when limit is breached, oldest alert will be removed||20|
|maxNotifications||How many Notifications can be displayed at one time||3|
|pauseWhenHovering||Pauses the Notification when mouse hovers over it||false|
|position||Where Notification will appear (if anywhere)||'BottomRight'|
|showProgressBar||Shows a Progress Bar in the Notification||false|
|transition||How Notification will appear: 'Bounce'||'Slide'|
As can be seen, many of the Alert Options properties relate to the appearance of the Notification that can be displayed when an Alert is triggered.
The Notification is only visible if the Alert Definition has
DisplayNotification set to true in Alert Properties
By default the Notification will appear by sliding into the BottomRight of the screen for 3 seconds without a progress bar and cannot be dragged nor will close when it is clicked.
However all these settings are configurable in Alert Options.
Unlike Alert Properties which can be set independently for each Alert Definition, Notifications are set in Alert Options and so are configured identically for every Alert which displays a notification
There are 2 Adaptable Events fired by the Alert Module:
The Alert Fired Event is fired every time an Alert is triggered.
It contains full details of the Alert and the associcated Alert Definition.
For Flashing Alerts the Event is Flashing Alert Fired.
EventInfo provides information about what (e.g. cell or row) was flashed, for how long, and the triggering data change.
Alerts includes the following UI Elements:
Popup - Shows a list of existing Alerts with Edit and Delete buttons. Plus an Add button to start the Alerts Wizard which facilitates the creation and editing of Alerts.
Toolbar - Updates when an Alert is triggered; contains an info button which when clicked gives full details of each Alert.
Tool Panel - Same as Toolbar above.
Column Menu -
Add / Remove Flashing Alert(or 'Off') Menu Item in numeric columns will enable / disable Flashing Cell Module for that Column.
Context Menu Item -
Clear AlertMenu Item clears a Cell if it has been coloured by an Alert
Alerts Entitlement Rules:
Full: Everything is available to the User
Hidden: Everything is hidden from the User and any Alerts supplied in Predefined Config will be ignored.
ReadOnly: Alerts will trigger as normal but users cannot not edit or delete them, nor create others.
Alert Predefined Config
The Alert section of AdapTable State enables Alert Definitions to be provided at design-time.
The Alert State contains a group of
AlertDefinition objects - each of which defines a rule which - when met - will fire the Alert.
Alert Definition Scope
Like many objects in AdapTable, Alert uses Scope to determine where an Alert should be applied.
The Scope can be one, some or all columns, or it can be all columns of a particular DataType (or DataTypes).
Can we show Alerts in the System Tray?
Not directly as its not something AdapTable can easily access. But we do publish the Alert Fired Event which allows you to show the Alert in multiple places.
I don't want my Alerts to pop-up. Can I prevent that?
Yes, when you create an Alert Definition you can stipulate, among other things, whether the Alert will display a Notification. See Alert Predefined Config for the full Alert Definition.
What is the difference between the Alert and the Reminder functions?
Reminders are, indeed, similar to Alerts but there are 2 key differences:
- the message is hard-coded rather than dynamically derived from the nature of the data change
- reminders are triggered, not when something changes in the Grid, but according to a Schedule set by the User when creating the Reminder.
Why add Prevent Edit Alerts which perform validation on the client - surely it should take place on the server?
You are right, validation should ideally take place on the server and hopefully it does for our users.
And AdapTable offers Server Validation for this reason.
Instead prevent edit Alerts validation specifically deals with 3 common use cases:
add an extra level of validation so that you can prevent edits which are usually permitted, but which in particular scenarios or use cases should be avoided
avoid unnecessary round trips to the server, particularly if this has other knock-on consequences or effect other users that might see their screen flash first with the new value and then again with the old value
as a temporary measure before Server Validation has been added; like all AdapTable objects, Alert Definitions will come into effect immediately after that they are created in the UI - there is no down-time needed, nor any custom development required, and no systems need to be restarted
Flashing Alert FAQ
Can we change the colours for a Flashing Cell column?
Yes you can choose any colours you want for both the up and down change.
Can we change the default colours?
Not at runtime - default colours can only be set at design tine in Alert Options
Can we change the colour based on the row (e.g. depending on other values in the row, the flash will be different colours or duration)?
Yes, simply create a new Flashing Alert Definition for that particular rule
Can we turn on flashing for columns which don't contain numbers?
Yes, Flashing Alert Definitions can be provided for any column or combination of columns
Can we add set the flash to remain in place until I see it?
Yes, set the
FlashDuration to always and it will remain coloured until explicitly cleared by the user
What is the difference between Alert Properties and Alert Options?
Alert Properties will define how Alerts trigged by one particular Alert Definition will behave. So you can set up different properties (e.g whether to show a notification or jump to the cell) based on the Alert Definition.
Alert Options governs behaviour across ALL Alerts (e.g. where Notifications should appear).