From 2af72ba9636bec70046394c41744f89ce4572e35 Mon Sep 17 00:00:00 2001 From: Ilia Motornyi Date: Thu, 3 Dec 2015 14:59:05 +0000 Subject: Revert "Merge branch 'documentation'" This reverts commit f6874bde3d945c8b2d1b5c17ab50e2d0f1f8ff00. Change-Id: I67ee1c30ba3e3bcc3c43a1dd2e73a822791514bf --- .../application/application-notifications.asciidoc | 177 --------------------- 1 file changed, 177 deletions(-) delete mode 100644 documentation/application/application-notifications.asciidoc (limited to 'documentation/application/application-notifications.asciidoc') diff --git a/documentation/application/application-notifications.asciidoc b/documentation/application/application-notifications.asciidoc deleted file mode 100644 index d58bf7b59a..0000000000 --- a/documentation/application/application-notifications.asciidoc +++ /dev/null @@ -1,177 +0,0 @@ ---- -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.WARNING_MESSAGE); ----- - -[[figure.notification.example1]] -.Notification -image::img/notification-example2.png[] - -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 last 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]#++
++#" 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 -<>. - -[[figure.notification.example2]] -.Notification with HTML Formatting -image::img/notification-example3.png[] - -[[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]#TYPE_HUMANIZED_MESSAGE# image:[]:: 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]#TYPE_WARNING_MESSAGE# image:[]:: 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]#TYPE_ERROR_MESSAGE# image:[]:: 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 box in the upper right corner indicates it visually. Unlike -with other notifications, the user can not interact with the application while -the error message is displayed. - -[parameter]#TYPE_TRAY_NOTIFICATION# image:[]:: 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. - - - - -ifdef::web[] -[[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. - -endif::web[] - -[[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]] -.A Styled Notification -image::img/notification-customization.png[] - - - - -- cgit v1.2.3