3.6. Error Handling

3.6.1. Error Indicator and message

All components have a built-in error indicator that can be set explicitly with setComponentError() or can be turned on implicitly if validating the component fails. As with component caption, the placement of the indicator is managed by the layout in which the component is contained. Usually, the error indicator is placed right of the caption text. Hovering the mouse pointer over the field displays the error message.

The following example shows how you can set the component error explicitly. The example essentially validates field value without using an actual validator.

// Create a field.
final TextField textfield = new TextField("Enter code");
main.addComponent(textfield);

// Let the component error be initially clear. (It actually is by default.)
textfield.setComponentError(null);

// Have a button right of the field (and align it properly).
final Button button = new Button("Ok!");
main.addComponent(button);
((VerticalLayout)main.getLayout()).setComponentAlignment(button, Alignment.BOTTOM_LEFT);

// Handle button clicks
button.addListener(new Button.ClickListener() {
    public void buttonClick(ClickEvent event) {
        // If the field value is bad, set its error.
        // (Here the content must be only alphanumeric characters.)
        if (! ((String) textfield.getValue()).matches("^\\w*$")) {
            // Put the component in error state and set the error message.
            textfield.setComponentError(new UserError("Must be letters and numbers"));
        } else {
            // Otherwise clear it.
            textfield.setComponentError(null);
        }
    }
});

Figure 3.9. Error indicator active

Error indicator active

The Form component handles and displays also the errors of its contained fields so that it displays both the error indicator and the message in a special error indicator area. See Section 4.15, “Form and Section 4.15.3, “Validating Form Input” for details on the Form component and validation of form input.

3.6.2. Notifications

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

Notifications are always associated with a window object, which can be a child window (the positioning is always relative to the entire browser view). The Window class provides a showNotification() method for displaying notifications. The method takes the caption and an optional description and notification type as parameters. The method also accepts a notification object of type Window.Notification, as described further below.

mainwindow.showNotification("This is the caption",
                            "This is the description");

Figure 3.10. Notification

Notification

The caption and description are, by default, written on the same line. If you want to have a line break between them, use the XHTML line break markup "<br/>". You can use any XHTML markup in the caption and description of a notification.

main.showNotification("This is a warning",
                            "<br/>This is the <i>last</i> warning",
                            Window.Notification.TYPE_WARNING_MESSAGE);

Figure 3.11. Notification with Formatting

Notification with Formatting

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 Window.Notification class.

Table 3.1. Types of Notifications

TYPE_HUMANIZED_MESSAGEA user-friendly message that does not annoy too much: it does not require confirmation by clicking and disappears very quickly. It is centered and has a neutral gray color.
TYPE_WARNING_MESSAGEWarnings 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.
TYPE_ERROR_MESSAGEError messages are notifications that require the highest user attention, with alert colors and by requiring 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.
TYPE_TRAY_NOTIFICATIONTray notifications are displayed in the "system tray" area, that is, in the lower-right corner of the browser view. As they do not usually obsure 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.

All of the features of specific notification types can be controlled with the attributes of Window.Notification. You can pass an explicitly created notification object to the showNotification() method.

// Create a notification with the default settings for a warning.
Window.Notification notif = new Window.Notification(
        "Be warned!", "This message lurks in the top-left corner!",
        Window.Notification.TYPE_WARNING_MESSAGE);

// Set the position.
notif.setPosition(Window.Notification.POSITION_TOP_LEFT);

// Let it stay there until the user clicks it
notif.setDelayMsec(-1);

// Show it in the main window.
main.showNotification(notif);

The setPosition() method allows setting the positioning of the notification. The method takes as its parameter any of the constants:

Window.Notification.POSITION_CENTERED 
Window.Notification.POSITION_CENTERED_TOP 
Window.Notification.POSITION_CENTERED_BOTTOM 
Window.Notification.POSITION_TOP_LEFT 
Window.Notification.POSITION_TOP_RIGHT 
Window.Notification.POSITION_BOTTOM_LEFT 
Window.Notification.POSITION_BOTTOM_RIGHT 

The setDelayMSec() allows you to set the time in milliseconds for how long the notification is displayed. Parameter value -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, as is default behaviour for error messages. It does not, however, add a close box that the error notification has.