123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183 |
- ---
- 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%]
|