Toast Messages
Toast messages can be either generated by the toast container or created and controlled manually. Allowing the container to generate them means that the positioning, stacking order and display timing will all be managed automatically and determined by the component initialisation properties.
Toast Message Example
To create a toast message, first define a block of HTML markup to serve as a template, then point the toastItemTemplate settings property to that template. A template can be any arbitrary piece of HTML, but must include the hidden class.
The following example shows how to set up toast messages.
NOTE: Many component instance properties are optional and can be omitted if the default settings are acceptable, but toastItemTemplate must be provided.
<div class="toast-item color-accent-4-dark background-light rounded-sm shadow-md hidden"
role="alert" id="toastItem1">
<div class="flex-row flex-nowrap align-items-center pad-sm">
<div class="flex-auto gap-horizontal-sm">
<span class="text-bold color-accent-3">≈</span><span class="text-bold text-sm">Notification</span>
</div>
<div class="flex-size-5">
<div class="text-bold text-xs time-element"></div>
</div>
<div class="flex-initial justify-content-end">
<div class="toast-close button-link width-xs-sm text-bold color-hover-info">✗</div>
</div>
</div>
<div class="flex-row flex-nowrap background-accent-4-light pad-sm rounded-bottom-sm">
<div class="flex-auto height-xs">
<div class="text text-sm">Your files have been received.</div>
</div>
</div>
</div>
<div id="toastContainer1"></div>
<div class="row text-bold text-sm">
<div class="col">
<button type="button" class="button-sm button-info" id="commandShowToast">Show Toast Message</button>
</div>
</div>
webui.ready( () => {
var toastContainer1 = ui("#toastContainer1").toastControl({
position: "top-right",
width: "25rem",
duration: 15000,
transitionDuration: 600,
toastItemTemplate: "#toastItem1",
toastItemOrder: "ascending",
autoHide: true
});
ui("#commandShowToast").click( () => {
ui("#toastItem1").find(".time-element").first().text(new Date().toLocaleTimeString('en-us'));
toastContainer1.showToastItem();
});
});
Toast Close ButtonWhen a toast close button is selected the toast container will take care of closing the toast message.
Toast Classes
The main toast message classes are described as follows.
| Class | Description |
|---|---|
| toast-container | The element used to contain all component generated toast messages. |
| toast-item | Defines a toast message. |
Functions
WebUI provides a set of standard JavaScript toast container functions. The behaviour of toast messages is controlled by the JavaScript initialisation as shown in the examples below.
| Function | Description |
|---|---|
| showToastItem() | Shows a toast message. |
| update(newSettings) | Updates the toast container instance at runtime using the configuration settings. |
Function Arguments
| Argument | Description |
|---|---|
| newSettings | An object literal containing a comma separated list of settings. |
Settings
Javascript settings available for the toast control.
| Property | Description |
|---|---|
| autoHide | Whether to hide the toast message automatically using the duration and transition settings. Can be true or false. Default: false. |
| displayOrder | The order in which tosat messages are stacked. Can be either "ascending" or "descending". Default: "ascending". |
| duration | The amount of time in milliseconds that the toast message is visible. An integer value. Default: 3000 |
| position | The initial starting position of the toast message batch. Can be "top-left", "top-center", "top-right", "bottom-left", "bottom-center", or "bottom-right". Default: "top-right". |
| toastItemTemplate | The HTML markup element used as a template. Required. (The toast container will clone the template as required.) |
| transitionDuration | The time taken in milliseconds for the toast message to fade in and out. An integer value. Default: 300. |
| width | The initial width of the toast container as a CSS string value, e.g. "60rem". Default: "25rem". |
Component Updates
Run-time Toast Message Updates
Settings specified for the toastControl instance can be updated programatically at run-time. See the following example, which updates the position and displayOrder settings. Use the restore button to revert the change.
<div class="row gap-md text-sm">
<div class="col-fixed">
<button id="toastUpdateShowCommand" class="button-sm menu-button-info">Show Toast Message</button>
</div>
<div class="col-fixed">
<button id="toastUpdateCommand" class="button-sm menu-button-info">Update</button>
</div>
<div class="col-fixed">
<button id="toastRestoreCommand" class="button-sm menu-button-info">Restore</button>
</div>
</div>
webui.ready( () => {
var toastContainer1 = ui("#toastContainer1").toastControl({
position: "top-right",
width: "25rem",
duration: 15000,
transitionDuration: 600,
toastItemTemplate: "#toastItem1",
toastItemOrder: "ascending",
autoHide: true
});
ui("#toastUpdateShowCommand").click( () => {
ui("#toastItem1").find(".time-element").first().text(new Date().toLocaleTimeString('en-us'));
toastContainer1.showToastItem();
});
ui("#toastUpdateCommand").click( () => {
toastContainer1.update({ position: "bottom-left", displayOrder: "descending" });
});
ui("#toastRestoreCommand").click( () => {
toastContainer1.update({ position: "top-right", displayOrder: "ascending" });
});
});
Events
Toast Message Event Callbacks
There are 4 event callbacks that can be used, ui.toast.show.before, ui.toast.show.after, ui.toast.hide.before, and ui.toast.hide.after. The following example shows how to setup the event callbacks.
webui.ready( () => {
toastContainer1.on("ui.toast.show.before", (e) => {
// Take some action
});
toastContainer1.on("ui.toast.show.after", (e) => {
// Take some action
});
toastContainer1.on("ui.toast.hide.before", (e) => {
// Take some action
});
toastContainer1.on("ui.toast.hide.after", (e) => {
// Take some action
});
});