3.5.7. Notifications

Notifications are pop-ups displayed in the center or in the corner of the main application window. They can disappear automatically or when the user clicks on the screen or presses Esc.

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

@Inject
private Notifications notifications;

@Subscribe("sayHelloBtn")
protected void onSayHelloBtnClick(Button.ClickEvent event) {
    notifications.create().withCaption("Hello!").show();
}

Notification can have a description which is displayed under the caption in a lighter font:

@Inject
private Notifications notifications;

@Subscribe("sayHelloBtn")
protected void onSayHelloBtnClick(Button.ClickEvent event) {
    notifications.create().withCaption("Greeting").withDescription("Hello World!").show();
}

Notifications can be of the following types:

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

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

  • WARNING – a warning. Disappears when the user clicks on the screen.

  • ERROR – a notification about an error. Disappears when the user clicks on the screen.

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

@Inject
private Notifications notifications;

@Subscribe("sayHelloBtn")
protected void onSayHelloBtnClick(Button.ClickEvent event) {
    notifications.create(Notifications.NotificationType.TRAY).withCaption("Hello World!").show();
}

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

@Inject
private Notifications notifications;

@Subscribe("sayHelloBtn")
protected void onSayHelloBtnClick(Button.ClickEvent event) {
    notifications.create()
            .withContentMode(ContentMode.HTML)
            .withCaption("<i>Hello World!</i>")
            .show();
}

When using HTML, don’t forget to escape data to prevent code injection.

You can pass true to the withHtmlSanitizer() method to enable HTML sanitization for the notification content. In this case, ContentMode.HTML parameter must be passed 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\")>";

@Inject
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 cuba.web.htmlSanitizerEnabled configuration property.

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

  • TOP_RIGHT

  • TOP_LEFT

  • TOP_CENTER

  • MIDDLE_RIGHT

  • MIDDLE_LEFT

  • MIDDLE_CENTER

  • BOTTOM_RIGHT

  • BOTTOM_LEFT

  • BOTTOM_CENTER

You can also set the delay in milliseconds before the notification disappears, using the withHideDelayMs() method. The -1 value is used to require the user to click the message.