Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 177 insertions, 0 deletions

diff --git a/documentation/application/application-notifications.asciidoc b/documentation/application/application-notifications.asciidoc
new file mode 100644
index 0000000000..d58bf7b59a
--- /dev/null
+++ b/documentation/application/application-notifications.asciidoc
@@ -0,0 +1,177 @@
+---
+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",
+    "<br/>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
+<<dummy/../../../framework/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[]
+
+[[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",
+    "<br/>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>>.
+
+[[figure.application.errors.notifications.css]]
+.A Styled Notification
+image::img/notification-customization.png[]
+
+
+
+