Overview

Information requiring the input from a user is presented in an Overlay. An overlay is centered on the screen, covering a portion of the UI, and typically blocks user interaction with other aspects of the ui.

Overlays are the container for standard form dialogs, confirmation and alert dialogs and notifications. Generally overlays display a View. (Its easy to create a View for a Vaadin component.) There are convenience methods for opening simple dialogs which just show text.

A key motivation for the overlay framework is the UX specification that a user can have dialogs open in mutliple locations at once. For example, if a user is editing a page component in a dialog - they can still open another page and open a component editor in a dialog.

UX Specifications

http://wiki.magnolia-cms.com/display/UX/Messages,+notifications+and+indications 
http://wiki.magnolia-cms.com/display/UX/Showing+notifications 
http://wiki.magnolia-cms.com/display/UX/Showing+indications

Terms

• LightDialog: a type of dialog that has the light look illustrated in the UX pages.
• Confirmation: a LightDialog with two buttons which can cancel an operation.
• Alert: a LightDialog with one button which forces user to acknoledge the notice.
• Notification: the note shown on the indications UX page.

Modality

In UI terms, a "modal window" or "modal dialog" is something that blocks interaction with the rest of the ui - so that you are in the "mode" of the window until you finish interacting with it and it closes. As AdminCentral is a sort of operating system we have a sophisticated system of modality.

ModalityDomain

An overlay can be modal over one of three domains, the shell, an app, or a subapp.
The classes which can host overlays implement the OverlayLayer interface. 

• Shell: An overlay on the shell prevents interaction with the entire ui.
  
  • A dialog about the entire AdminCentral interface would be opened on the shell.
• App: An overlay on an app prevents any interaction with the app, but you can still work with other apps and the shell. 
  
  • The overlay only covers the one app it is opened on. For example with an overlay opened on an app, you can still launch or switch to other apps the App Launcher and intreract with them. It is possible to have multiple apps with overlays open on them at the same time.
  • Used to display a settings dialog pertaining to the app.
• SubApp: An overlay on a subapp prevents interation only with one subapp. 
  
  • You can still interact with other subapps in the same app - or access other apps. It is possibel to have multiple subapps with overlays on them at the same time.
  • Used to interact with one subapp, such as dialogs opening in the PageEditor.

The blue region in this diagram shows which part of the UI is blocked.

ModalityLevel

Overlays can present their modality in three ways.

• Strong: The overlay has a dark curtain behind it which blocks interaction with the user interface it covers. (Normal dialogs use this)
• Light: The overlay has a light wide border and a light or invisible curtain behind it which blocks interaction with the user interface it covers. (Light dialogs use this Confirmations/Alerts)
• Non-Modal: The overlay has no curtain and does not block interaction with the user interface it covers. (Notifications use this)

Usage and Examples

The OverlayLayer interface provides methods to open overlays. OverlayLayer is implemented by the contexts: Shell, App, SubApp.

Note that each of these implementors set the ModalityDomain to the appropriate level for their context.

Simple Example

subAppContext.openOverlay(myView);

Often you won't need to call openOverlay yourself, there are convenient methods for opening Alerts, Confirmations, and Notfications:

• OverlayLayer.openAlert(...);
• OverlayLayer.openConfirmation(...);
• OverlayLayer.openNotification(...);

All of these methods take a View which allows an implementor to add any Vaadin Component to the overlay. This enables a developer to add anything, such as a form.
Convenience methods allow developers to just provide strings as this is the most common use case.

Callbacks enable code to take action based on user interaction in the overlay:

• openConfirmation takes a ConfirmationCallback with methods 
  
  • onSuccess()
  • onCancel()
• openAlert takes an optional AlertCallback with method
  
  • onOk()
• openNotification takes an optional NotificationCallback with method
  • onLinkClick()

FYI: Other classes take an OverlayLayer implementor as a parameter so that they can open an Overlay in the proper modality domain.

• ChooseDialogs can be opened on a ContentApp with openChooseDialog().
• FormDialogs are opened with FormDialogPresenter with start()

How to get an OverlayLayer implementor

To display an overlay you need an OverlayLayer implementor. Which one you use determines the ModalityDomain of your overlay.
You can get a Shell, AppContext, or SubAppContext via dependency injection.

UiContext

The UiContext interface provides a special very convenient way to get an OverlayLayer. UiContext extends OverlayLayer.

A class with an injected UiContext always contains the context in which the class was created. 
So when in a class where you dont necessarily know in which context you should create the overlay, inject the UiContext.

For example, the BasicUploadFieldBuilder gets the UiContext injected because the field could be created in an app or in a sub app, the code does not know.

Examples:

Example:

View myView = new View() {

            @Override
            public Component asVaadinComponent() {
return new Button("Look ma, no hands!");

}
};

OverlayCloser myOverlay = subAppContext.openOverlay(myView);

Example:

To have the button close the overlay:

final Button myComponent = new Button("Look ma, no hands!");

        View myView = new View() {

            @Override

            public Component asVaadinComponent() {

                return myComponent;

            };

        };

        final OverlayCloser myOverlay = subAppContext.openOverlay(myView);

        myComponent.addClickListener( new Button.ClickListener() {

            @Override

            public void buttonClick(ClickEvent event) {

                myOverlay.close();

            };

        });

Implementation Note - Management of Overlays by Shell

In order to prevent the "class sprawl" that would result from modifying all potential server ui components that could host an overlay to actually accept an overlay as a child - the Shell is the parent of all of the overlays.
But to facilitate the stacking of all of the overlays in the correct position, the actual html DOM of the overlays is appended to the actual widget that the overlay is covering. 

In other words: The framework allows us to attach the clientside of components, wrapped in an overlay, to any component, without that component needing to implement Vaadin's "hasComponents" interface.