Toast Notifications

Kanoa MES can show toast notifications on any Perspective page: short messages that slide in at the edge of the screen and close on their own. Toasts are powered by react-toastify and are shown from scripts using the system.kanoa.toast functions. Nothing needs to be placed on a view. Every Perspective page in every project can show toasts as soon as the module is installed.

system.kanoa.toast.show({"message": "Lot 123 released", "type": "success"})

Up to 25 toasts are shown on a page at once. Any beyond that wait until space frees up.

Script Functions

Function	Description
system.kanoa.toast.show	Shows a toast and returns its id.
system.kanoa.toast.update	Changes a toast that is still on screen.
system.kanoa.toast.dismiss	Closes one toast, or every toast on the page.

Default Values

Any key you leave out of the dictionary uses these defaults.

Key	Default
message	None. Required for show.
title	None. No heading is shown.
type	default
position	bottom-center
animate	bounce
autoClose	5000 (5 seconds)
closeButton	True
pauseOnHover	True
draggable	Swipe to dismiss on touch screens only. Pass True to allow dragging with a mouse as well.
loading	False
id	A generated UUID, returned by show.
sessionId	The session the calling Perspective script is running on. Required from Gateway scripts.
pageId	The page the calling Perspective script is running on. Required from Gateway scripts.

Which Page Shows the Toast

• From a Perspective script (a component event, view script, message handler or session event), the toast goes to the page the script is running on. sessionId and pageId are not needed.
• From a Gateway script (a tag change script, timer, WebDev endpoint, or any code run through system.util.invokeAsynchronous), there is no current page, so pass both sessionId and pageId. This works the same way as system.perspective.sendMessage.
• From the Designer Script Console, the functions raise an error. They are Perspective-only.

Invalid arguments (an unknown type, text over the length limit, a missing message) raise an error in the calling script rather than being silently ignored.

Loading Toasts

For work that takes a moment, show a loading toast first and then update it with the result. A loading toast shows a spinner, has no close button and stays open until you update it.

import time
toastId = system.kanoa.toast.show({"message": "Releasing lot 123...", "loading": True})
try:
    releaseLot(123)
    time.sleep(3)
    system.kanoa.toast.update({"id": toastId, "message": "Lot 123 released", "type": "success"})
except:
    system.kanoa.toast.update({"id": toastId, "message": "Release failed", "type": "error"})
    raise

Updating a loading toast without "loading": True stops the spinner and gives it back its close button and auto-close timer. To change the message while keeping the spinner (for example, to show progress), pass "loading": True again. To make sure a loading toast cannot stay open forever if a script fails, give it an autoClose when you show it.

If the work runs in the background with system.util.invokeAsynchronous, read the session and page ids before starting, and pass them to update:

sessionId, pageId = self.session.props.id, self.page.props.pageId
toastId = system.kanoa.toast.show({"message": "Working...", "loading": True})

def work():
    # ... long task ...
    system.kanoa.toast.update({"id": toastId, "message": "Done", "type": "success",
                               "sessionId": sessionId, "pageId": pageId})

system.util.invokeAsynchronous(work)

Text Is Always Plain Text

The message and title are displayed exactly as written. HTML tags appear as literal text and are never interpreted, so it is safe to show values that came from users, tags or the database.

Component Events

Toasts report their lifecycle to the view that showed them. These events are added to every Perspective container, but only fire on a view's root container. They appear in the root container's event configuration in the Designer.

For a toast shown from a Perspective script, the event fires on the root container of the view the script is running in. For a toast shown from a Gateway script, it fires on the page's primary view. Each toast fires one onToastOpen and one onToastClose. Nothing fires if the view has already closed.

onToastOpen

Triggered when a toast shown by this view opens.

Property	Type	Description
event.id	string	The toast's id, as returned by system.kanoa.toast.show.

onToastClose

Triggered when a toast shown by this view closes, whether it timed out, was dismissed by a script, or was closed by the user.

Property	Type	Description
event.id	string	The toast's id, as returned by system.kanoa.toast.show.
event.removedByUser	boolean	true when the user closed the toast (close button, click or swipe).

Styling Toasts

Default: Toasts Follow the Perspective Theme

With no setup, toasts take their colors, font, corner radius and shadow from the session's Perspective theme:

• The background and text use the theme's --containerRoot and --label.
• info, success, warning and error toasts use the theme's --info, --success, --warning and --error.
• The progress bar and loading spinner use --callToAction.

Switching themes (for example, setting session.props.theme to kanoa-dark) restyles toasts that are already on screen. Custom themes built on Perspective's standard variables get matching toasts automatically.

A theme counts as dark when dark is one of the hyphen-separated words in its name (dark, dark-cool, kanoa-dark, ...).

Overriding Colors and Sizes

To change how toasts look, set any of these CSS variables. Each one falls back to the Perspective theme variable shown, and then to a fixed value if the theme does not define that.

Variable	Controls	Default
--kanoa-toast-background	Toast background	--containerRoot
--kanoa-toast-text	Message and title text	--label
--kanoa-toast-info	info toast accent and icon	--info
--kanoa-toast-success	success toast accent and icon	--success
--kanoa-toast-warning	warning toast accent and icon	--warning
--kanoa-toast-error	error toast accent and icon	--error
--kanoa-toast-progress	Auto-close progress bar	--callToAction
--kanoa-toast-spinner	Loading spinner	--callToAction
--kanoa-toast-spinner-track	Loading spinner's empty track	--neutral-30
--kanoa-toast-font-family	Font	--font-NotoSans
--kanoa-toast-border-radius	Corner radius	--borderRadius
--kanoa-toast-shadow	Drop shadow	--boxShadow3
--kanoa-toast-width	Toast width	320px
--kanoa-toast-z-index	Stacking order	14015

Set them on :root:

:root {
  --kanoa-toast-background: #1E2A38;
  --kanoa-toast-text: #F4F4F4;
  --kanoa-toast-success: #2ECC71;
  --kanoa-toast-font-family: "Inter", sans-serif;
}

Set the --kanoa-toast-* variables, not react-toastify's own --toastify-* variables. The --toastify-* variables are set by the module and overriding them is not reliable.

Where to Put Your Overrides

• In a Perspective theme file, to apply to every project that uses that theme. Perspective loads only the active theme's CSS, so you can give each theme its own toast colors: put dark values in your dark theme and light values in your light theme.
• In a project's advanced stylesheet, to apply to one project whatever its theme.

Styling Beyond Colors

For borders, layout or typography, target these class names. Start each selector with #kanoa-toast-root so it takes priority over the built-in styles without !important.

Class	Element
.Toastify__toast	Every toast
.Toastify__toast--info, --success, --warning, --error, --default	Toasts of that type
.Toastify__toast-theme--light, .Toastify__toast-theme--dark	Toasts on a light or dark theme
.kanoa-toast__title	The title
.kanoa-toast__message	The message
.Toastify__progress-bar	The auto-close progress bar
.Toastify__close-button	The close button

#kanoa-toast-root .Toastify__toast--error {
  border-left: 4px solid var(--error);
}

#kanoa-toast-root .kanoa-toast__title {
  text-transform: uppercase;
}

Layering

Toasts appear above docked views, Perspective's connection and notification banners, tooltips and modal popups, and below the Perspective app bar. To change this, set --kanoa-toast-z-index.