vaadin-framework/documentation/application/application-notifications.asciidoc

---
title: Notifications
order: 7
layout: page
---

[[application.notifications]]
= Notifications

Notifications are error or information boxes that appear briefly, typically at
the center of the screen. A notification box has a caption and an optional
description and icon. The box stays on the screen either for a preset time or
until the user clicks it. The notification type defines the default appearance
and behaviour of a notification.

There are two ways to create a notification. The easiest is to use a static
shorthand [methodname]#Notification.show()# method, which takes the caption of
the notification as a parameter, and an optional description and notification
type, and displays it in the current page.


[source, java]
----
Notification.show("This is the caption",
                  "This is the description",
                  Notification.Type.HUMANIZED_MESSAGE);
----

[[figure.notification.example1]]
.Notification
image::img/notification-example2.png[width=50%, scaledwidth=80%]

For more control, you can create a [classname]#Notification# object. Different
constructors exist for taking just the caption, and optionally the description,
notification type, and whether HTML is allowed or not. Notifications are shown
in a [classname]#Page#, typically the current page.


[source, java]
----
new Notification("This is a warning",
    "This is the <i>last</i> warning",
    Notification.Type.WARNING_MESSAGE, true)
    .show(Page.getCurrent());
----

The caption and description are by default written on the same line. If you want
to have a line break between them, use the HTML line break markup "
[literal]#++<br/>++#" if HTML is enabled, or " [literal]#++\n++#" if not. HTML
is disabled by default, but can be enabled with
[methodname]#setHtmlContentAllowed(true)#. When enabled, you can use any HTML
markup in the caption and description of a notification. If it is in any way
possible to get the notification content from user input, you should either
disallow HTML or sanitize the content carefully, as noted in
<<../advanced/advanced-security#advanced.security.sanitizing,"Sanitizing
User Input to Prevent Cross-Site Scripting">>.

[[figure.notification.example2]]
.Notification with HTML Formatting
image::img/notification-example3.png[width=30%, scaledwidth=60%]

[[application.notifications.type]]
== Notification Type

The notification type defines the overall default style and behaviour of a
notification. If no notification type is given, the "humanized" type is used as
the default. The notification types, listed below, are defined in the
[classname]#Notification.Type# class.

[parameter]#HUMANIZED_MESSAGE#::
image:img/notification-humanized.png[width=30%, scaledwidth=50%]
+
A user-friendly message that does not annoy too much: it does not require
confirmation by clicking and disappears quickly. It is centered and has a
neutral gray color.

[parameter]#WARNING_MESSAGE#::
image:img/notification-warning.png[width=30%, scaledwidth=50%]
+
Warnings are messages of medium importance. They are displayed with colors that
are neither neutral nor too distractive. A warning is displayed for 1.5 seconds,
but the user can click the message box to dismiss it. The user can continue to
interact with the application while the warning is displayed.

[parameter]#ERROR_MESSAGE#::
image:img/notification-error.png[width=30%, scaledwidth=50%]
+
Error messages are notifications that require the highest user attention, with
alert colors, and they require the user to click the message to dismiss it. The
error message box does not itself include an instruction to click the message,
although the close icon on the right side indicates it visually. Unlike
with other notifications, the user can not interact with the application while
the error message is displayed. If you don't want to show the close icon,
you can hide by adding the style constant
[literal]#ValoTheme.NOTIFICATION_CRITICAL_ERROR# to the [classname]#Notification#.

[parameter]#TRAY_NOTIFICATION#::
image:img/notification-tray.png[width=30%, scaledwidth=50%]
+
Tray notifications are displayed in the "system tray" area, that is, in the
lower-right corner of the browser view. As they do not usually obscure any user
interface, they are displayed longer than humanized or warning messages, 3
seconds by default. The user can continue to interact with the application
normally while the tray notification is displayed.


[[application.notifications.customization]]
== Customizing Notifications

All of the features of specific notification types can be controlled with the
[classname]#Notification# properties. Once configured, you need to show it in
the current page.


[source, java]
----
// Notification with default settings for a warning
Notification notif = new Notification(
    "Warning",
    "Area of reindeer husbandry",
    Notification.TYPE_WARNING_MESSAGE);

// Customize it
notif.setDelayMsec(20000);
notif.setPosition(Position.BOTTOM_RIGHT);
notif.setStyleName("mystyle");
notif.setIcon(new ThemeResource("img/reindeer.png"));

// Show it in the page
notif.show(Page.getCurrent());
----

The [methodname]#setPosition()# method allows setting the positioning of the
notification. The position can be specified by any of the constants defined in
the [classname]#Position# enum.

The [methodname]#setDelayMSec()# allows setting the time for how long the
notification is displayed in milliseconds. Parameter value [literal]#++-1++#
means that the message is displayed until the user clicks the message box. It
also prevents interaction with other parts of the application window, which is
the default behaviour for error notifications. It does not, however, add a close
box that the error notification has.


[[application.notifications.css]]
== Styling with CSS


[source, css]
----
.v-Notification {}
  .popupContent {}
    .gwt-HTML {}
      h1 {}
      p  {}
----

The notification box is a floating [literal]#++div++# element under the
[literal]#++body++# element of the page. It has an overall
[literal]#++v-Notification++# style. The content is wrapped inside an element
with [literal]#++popupContent++# style. The caption is enclosed within an
[literal]#++h1++# element and the description in a [literal]#++p++# element.

To customize it, add a style for the [classname]#Notification# object with
[methodname]#setStyleName("mystyle")#, and make the settings in the theme, for
example as follows:


[source, css]
----
.v-Notification.mystyle {
    background: #FFFF00;
    border: 10px solid #C00000;
    color: black;
}
----

The result is shown, with the icon set earlier in the customization example, in
<<figure.application.errors.notifications.css>>.

[[figure.application.errors.notifications.css]]
.A Styled Notification
image::img/notification-customization.png[width=40%, scaledwidth=60%]