Notifications

LIVE DEMO

Notifications are pop-up messages displayed in the center or the corner of the main application window. Use notifications to inform users about activities, processes, and events in the application.

Notifications can disappear automatically or when the user clicks on the screen or presses Esc.

To show a notification, inject the Notifications bean into the screen controller and use its fluent interface. In the following example, a notification is shown on the button click:

@Autowired
private Notifications notifications;

@Subscribe("simple")
public void onSimpleClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Upload successful!")
            .show();
}

Text Content

To set the caption of a notification, use the withCaption() method. You can use localized messages from the main message pack.

Notification can have a description displayed under the caption in a lighter font. Use the withDescription() method to pass the description text.

@Autowired
private Notifications notifications;

@Subscribe("withDescription")
public void onWithDescriptionClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Upload complete!")
            .withDescription("Your file was uploaded successfully")
            .show();
}

Using the withContentMode() method, you can define how the message text should be displayed. There are three predefined content modes:

  • ContentMode.TEXT - textual values are displayed as plain text. This mode is the default.

  • ContentMode.PREFORMATTED - textual values are displayed as preformatted text. In this mode, newlines are preserved when rendered on the screen. ContentMode.PREFORMATTED is not supported for notifications.

  • ContentMode.HTML - textual values are interpreted and displayed as HTML. When using HTML, don’t forget to escape data to prevent code injection.

You can use \n characters for line breaks in messages. In order to show HTML, use the withContentMode() method with ContentMode.HTML parameter.

@Autowired
private Notifications notifications;

@Subscribe("withContent")
public void onWithContentClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("<i>Upload complete!</i>")
            .withContentMode(ContentMode.HTML)
            .show();
}

You can pass true to the withHtmlSanitizer() method to enable HTML sanitization for the notification content. In this case, pass the ContentMode.HTML parameter to the withContentMode() method.

protected static final String UNSAFE_HTML = "<i>Jackdaws </i><u>love</u> " +
        "<font size=\"javascript:alert(1)\" " +
        "color=\"moccasin\">my</font> " +
        "<font size=\"7\">big</font> <sup>sphinx</sup> " +
        "<font face=\"Verdana\">of</font> <span style=\"background-color: " +
        "red;\">quartz</span><svg/onload=alert(\"XSS\")>";

@Autowired
private Notifications notifications;

@Subscribe("showNotificationOnBtn")
public void onShowNotificationOnBtnClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Notification with Sanitizer")
            .withDescription(UNSAFE_HTML)
            .withContentMode(ContentMode.HTML)
            .withHtmlSanitizer(true)
            .show();
}

@Subscribe("showNotificationOffBtn")
public void onShowNotificationOffBtnClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Notification without Sanitizer")
            .withDescription(UNSAFE_HTML)
            .withContentMode(ContentMode.HTML)
            .withHtmlSanitizer(false)
            .show();
}

The value passed to the withHtmlSanitizer() method overrides the value of global jmix.ui.component.htmlSanitizerEnabled configuration property.

Notification Type

Notifications can be of the following types:

  • TRAY - a notification is displayed in the bottom right corner of the application and disappears automatically.

    tray

  • HUMANIZED - a standard notification is displayed in the center of the screen, disappears automatically.

    humanized

  • WARNING - a warning notification is displayed in the center of the screen. It disappears when the user clicks on the screen.

    warning

  • ERROR - a notification about an error is displayed in the center of the screen. It disappears when the user clicks on the screen.

    error

  • SYSTEM - a system notification is displayed in the top center of the screen. It disappears when the user clicks on the notification.

    system

The default type is HUMANIZED. You can provide a different kind in the create() method:

@Autowired
private Notifications notifications;

@Subscribe("withType")
public void onWithTypeClick(Button.ClickEvent event) {
    notifications.create(Notifications.NotificationType.TRAY)
            .withCaption("Upload complete!")
            .withDescription("Your file was uploaded successfully")
            .show();
}

Position

You can set the position of the notification using the withPosition() method. The standard values are:

  • DEFAULT

  • TOP_RIGHT

  • TOP_LEFT

  • TOP_CENTER

  • MIDDLE_RIGHT

  • MIDDLE_LEFT

  • MIDDLE_CENTER

  • BOTTOM_RIGHT

  • BOTTOM_LEFT

  • BOTTOM_CENTER

Delay

Notifications with the TRAY, HUMANIZED types stay on-screen for 3 seconds by default.

Notifications with the WARNING, ERROR, and SYSTEM types require the user to click the message.

You can set the delay in milliseconds before the notification disappears, using the withHideDelayMs() method. Setting the delay to -1 disables auto-closing, keeping the notification visible until the user clicks on it.

Styling

Using the withStyleName() method, you can set the custom CSS style name for the notification. See Creating New Styles for details.