Differences

This shows you the differences between two versions of the page.

--- en:outskirts:mages-peaks:toasts [2023/11/12 21:30] – removed - external edit (Unknown date) 127.0.0.1
+++ en:outskirts:mages-peaks:toasts [2024/10/28 08:00] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Notifications Management (Toasts & Modal) ======
+===== What are Toasts ? =====
+Bootstrap Toasts are managed, and can be invoked programmatically.
+They will display above the Map Area. **Several Toasts can be displayed simultaneously, they will stack vertically.**
+See [[https://getbootstrap.com/docs/5.3/components/toasts/]]
+A full Toast is composed of either or both:
+  * a Title text
+  * a Text body
+  * Plus an (optional) colored tag (''bg-danger, bg-warning, bg-info, bg-success'' )
+It can have an [X] button to make it ''closeable'' by the user (otherwise, only the code can close it).
+It can close itself after a specified delay (''autohide'' feature).
+{{en:outskirts:mages-peaks:classictoasts.png}}
+A specific type is also supported: "''cancellable''" toasts, having a cancel button enabling the user to cancel a pending action.
+{{en:outskirts:mages-peaks:canceltoast.png}}
+For this type of Toast, an "action" button can be provided, enabling the user to trigger or confirm an action (here, for example, the user can select any map location and when he has the right one, he clicks on 'associate').
+{{en:outskirts:mages-peaks:actiontoast.png?400|}}
+==== Sample Uses ====
+Toasts can be used to:
+  * Notify that an operation failed
+  * Notify the success of an asynchronous operation
+  * Notify an event
+  * Materialize a pending user action (cancellable)
+  * Let the user interact with the Map and trigger a pending action
+==== API ====
+A Toast is created using ''toastStore.showToast(toastDefinition)''. It can closed by the user (if closeable), closed automatically after a preset time (if autohide) or closed by API: ''toastStore.closeToast(id)''.
+The Toast Definition is as follows:
+<code>
+export interface ToastDef {
+  /** The Toast Header will be shown with this title.  */
+  title?: string;
+  /** The tag color class besides Title or Body. Tag Absent if not specified. */
+  tagColor?: 'bg-danger' | 'bg-warning' | 'bg-info' | 'bg-success';
+  /** Text in the body, if any. */
+  bodyText?: string;
+  /**
+   * Close mode:
+   * - closeable: Only the [X] close button.
+   * - autohide: Only after hideDelay millis
+   * - closeable+autohide: Both the [X] close button and the hideDelay millis
+   * - cancellable: Cancel button. No [X], no autohide. Possible action Button also.
+   * - no-close: only the code can dismiss this Toast.
+   */
+  closeMode: CloseMode;
+  /** If auto-hide, gives the delay (millis). Default 5000. */
+  hideDelay?: number;
+  /** If cancellable, this is the callback method. */
+  onEnded?: (how: "cancel" | "action") => void;
+  /** If cancellable, this adds an 'action' button also with this text. */
+  actionLabel?: string;
+}
+</code>
+===== Modals =====
+The `Modal.svelte` component is provided for simple Modals.
+{{en:outskirts:mages-peaks:modal.png?400|}}
+It can accept any number of buttons, with a specified label, className (btn-primary, btn-secondary ...) and actionName. If the modal is closed by clicking on a button, the `onClose` method will receive this actionName as argument (if the modal is closed by the [X] button, `cancel` will be received).
+==== Adding a Modal ====
+Just insert a <Modal> component in your component, as shown below:
+<code>
+  <Modal
+    title="Select a Map location"
+    bodyText="Please select on the Map the location to associate with this Node."
+    buttons={[
+      { label: "cancel", actionName: "cancel", className: "btn-secondary" },
+    ]}
+    open={isOpen}
+    onClose={processModal}
+  />
+</code>