Web Notifications (Toastr)
Last updated
Last updated
ToastR is a lightweight and flexible web widget for displaying in-app notifications. These notifications are ideal for providing brief, non-intrusive feedback to users, such as status updates, error messages, or success confirmations. ToastR notifications can be highly customized to fit the look and feel of your application.
The plugins.webnotificationsToastr API allows you to create and manage these notifications efficiently, with options for global settings, animation, and event handling.
To be able to use Toastr Web Notifications, the Web Notifications package must be added from Services section of Servoy Package Manager. It can be accessed by code using plugins.webnotificationsToastr.
Key Features:
Customizable Content: Easily define titles, messages, and styles for your notifications.
Support for Actions: Include interactive elements like action buttons to enhance user engagement.
Positioning Options: Choose where notifications appear on the screen (e.g., top-right, bottom-left).
Visual Feedback: Add progress bars, animations, and HTML content for enhanced visuals.
Event Handling: Attach callback functions to handle user interactions, such as clicks or button presses.
Global and Individual Settings: Set default configurations globally or customize individual notifications as needed.
ToastR web notifications implementation is based on the NGX-TOASTR. You can find information about this library here.
ToastR notifications are versatile and can be used in various scenarios to improve user experience and communication within the application. Here are some common use cases:
Acknowledgements:
Notify users of successful actions, such as form submissions, data saving, or record updates.
Example: "Your profile was updated successfully."
Error Handling:
Alert users about issues like validation errors, failed processes, or missing inputs.
Example: "Error: Unable to connect to the server."
Informational Updates:
Share announcements, reminders, or system messages without interrupting the user's workflow.
Example: "Scheduled maintenance will occur at 10:00 PM."
Warnings:
Caution users about potentially harmful actions, such as deleting important data or navigating away with unsaved changes.
Example: "Warning: Unsaved changes will be lost if you leave this page."
Interactive Prompts:
Use action buttons to let users confirm or cancel (close button) actions directly within the notification.
Example: "Do you want to proceed with the operation? [Proceed]"
ToastR supports four main types of notifications, each with a specific purpose and visual style:
Success notifications are designed to celebrate or acknowledge positive outcomes. They are usually green to signal success.
Example:
Info notifications are neutral and typically blue. They are ideal for sharing general updates or non-critical information.
Example:
Error notifications are red and signal issues or problems that need attention. They are effective for displaying critical messages.
Example:
Warning notifications are typically yellow or orange. They are used to caution users about potential risks or actions.
Example:
The ToastR API provides several configuration options to customize the behavior and appearance of notifications. These options can be set globally using setGlobalOptions() or individually for each notification.
Available Options:
actionButton: Enables a custom button within the notification for additional user actions.
example: actionButton: true
actionButtonText: Specifies the text for the action button, which can also include HTML.
example: "actionButtonText: <b>Learn More</b>"
closeButton: Adds a close button to the notification for manual dismissal.
example: closeButton: true
disableTimeOut: Prevents the notification from closing automatically, requiring manual dismissal.
example: disableTimeOut: true
enableHtml: Allows the notification message to include HTML content.
example: enableHtml: true
extendedTimeOut: Sets the delay (in milliseconds) before the notification closes after user interaction.
example: extendedTimeOut: 5000
hideDuration: Sets the duration (in milliseconds) for the hide animation when the notification closes.
example: hideDuration: 2000
positionClass: Determines where the notification appears on the screen (e.g., top-right, bottom-left).
example: positionClass: "toast-bottom-left"
progressBar: Displays a progress bar showing the remaining time before the notification closes.
example: progressBar: true
showDuration: Sets the duration (in milliseconds) for the show animation when the notification appears.
example: showDuration: 2000
tapToDismiss: Allows the user to dismiss the notification by clicking or tapping on it.
example: tapToDismiss: true
timeOut: Specifies the time (in milliseconds) the notification remains visible before automatically closing.
example: timeOut: 3000
You can customize ToastR notifications, preview them and get their details here.
This example demonstrates how to display a success notification with a custom title and additional visual options.
Explanation:
Purpose:
Notify the user that an operation, such as saving data, was completed successfully.
Success notifications are typically green to signal positive outcomes.
API Method:
The success method is used to create a green notification. Parameters:
"Data saved successfully!": The message displayed to the user.
"Success": The optional title that appears above the message.
{ progressBar: true, positionClass: "toast-top-right" }: Custom options:
progressBar: true displays a progress bar to indicate the remaining visible time.
positionClass: "toast-top-right" positions the notification in the top-right corner of the screen.
Use Case:
Useful after completing a task like saving form data, updating a record, or submitting a successful request.
This example displays an error notification and triggers a callback function when the user clicks on it.
Explanation:
Purpose:
Inform the user about an issue, such as a failed save operation, and optionally allow interaction (e.g., retry or display details).
Error notifications are typically red to indicate a problem.
API Method:
The error method is used to create a red notification.
Parameters:
"An error occurred while saving data.": The message informing the user of the issue.
"Error": The optional title for clarity.
null: No additional options are passed in this case.
"errorToastID": A unique identifier for this notification, useful for tracking or clearing it later.
function (toastrId) { ... }: A callback function executed when the user clicks the notification. It logs the notification ID to the console.
Use Case:
Ideal for alerting users to errors such as failed data submission or invalid input.
The callback allows additional functionality, like retrying the operation or navigating to a specific screen.
This example creates an interactive notification that includes an action button for additional user engagement.
Explanation:
Purpose:
Provide the user with actionable feedback, such as prompting them to confirm or proceed with a critical operation.
Informational notifications are typically blue to indicate neutrality.
API Method:
The info method is used to create a blue notification.
Parameters:
"Do you want to proceed with the operation?": A question or prompt for the user.
"Action Required": A clear title emphasizing the need for user attention.
{ actionButton: true, actionButtonText: "Proceed" }: Custom options:
actionButton: true enables a button within the notification.
actionButtonText: "Proceed" sets the button’s label, which can also include HTML if needed.
null: No specific ID is provided for this notification.
function (toastrId) { ... }: A callback function logs the notification ID to the console when the user clicks the button.
Use Case:
Useful for tasks requiring user confirmation, such as deleting records, submitting important data, or starting irreversible processes.
The action button provides a direct way for users to respond, making it highly interactive.
