Overlays and modality - 5 UI

Deprecated

Overlays and modality have been deprecated since Magnolia 6.0. They are part of the Magnolia 5 UI framework.

For the updated implementation, see the light property in Dialog definition for Magnolia 6 UI instead.

Information requiring the input from a user is presented in an overlay. Overlays are the container for standard dialogs and messages. Typically, overlays display a view. The key benefit of the overlay framework is that it allows a user to work in multiple dialogs in different locations simultaneously. For example, a user editing a component on a page can open another component dialog on a different page without closing the first dialog.

Modality

A modal dialog is one that blocks interaction with other parts of the interface. The user is in the mode of the interface that is requesting information and is forced to close it before moving on to other tasks. The rest of the interface remains non-functional while the modal dialog is open.

Domain

There are three modality domains. The domains represent what will be blocked by the opened dialog:

Shell overlay prevents interaction with the entire UI. Dialogs relevant to the entire AdminCentral interface are modal to the shell.
App overlay prevents interaction with the app. Users can still work with other apps and the shell. Used to display a settings pertaining to the app.
Subapp overlay prevents interaction with the subapp. Users can still interact with other subapps and other apps. Used in the page editor.

Domain structure

Level

Overlays can present their modality in three ways.

Strong: The overlay has a dark curtain behind it that blocks interaction with the part of the interface it covers. Standard dialogs use this.

Import form

Light: The overlay has a light wide border and a light or invisible curtain behind it that blocks interaction with the part of the interface it covers. Light dialogs and alerts use this.

Rename contact form

Non-modal: The overlay has no curtain and does not block interaction with the part of the interface it covers. Pop-ups use this.

Publication failed pop-up

Usage

Classes that can host overlays implement the OverlayLayer interface. The interface provides methods to open overlays. OverlayLayer is implemented by the contexts: shell, app and subapp.

Each implementor sets the modality domain to the appropriate level for its context.

Opening an overlay

subAppContext.openOverlay(myView);

You probably do not need to call openOverlay yourself because there are convenience methods for showing messages:

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

These methods take a view that allows an implementor to add any Vaadin component to the overlay. For example you could add a form. The most common use case is to simply provide a string.

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

openConfirmation takes a ConfirmationCallback with methods:
- onSuccess()
- onCancel()
openAlert takes an AlertCallback with an optional implementation of method onOk().
openNotification takes an optional NotificationCallback with method onLinkClick().

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

Choose dialogs can be opened on a content app with openChooseDialog().
Dialogs are opened with FormDialogPresenter with start().

Getting an OverlayLayer implementor

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

The UiContext interface provides a way to get an OverlayLayer. UiContext extends OverlayLayer. A class with an injected UiContext always contains the context in which the class was created. In a class, if you are unsure 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 subapp, the code does not know this.

Examples

Here are a few code examples that you can adapt to suit.

Example 1

Overlay in subapp context

View myView = new View() {

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

OverlayCloser myOverlay = subAppContext.openOverlay(myView);

Example 2

Closing the overlay with a button

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();
        };
    });

Example 3

To display a modal dialog with a different modality level, you can specify a ModalityLevel as the second parameter:

myOverlay = subAppContext.openOverlay(myView,ModalityLevel.STRONG);
myOverlay = subAppContext.openOverlay(myView,ModalityLevel.LIGHT);
myOverlay = subAppContext.openOverlay(myView,ModalityLevel.NON_MODAL);

Light modality level in subapp context

View myView = new View() {

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

OverlayCloser myOverlay = subAppContext.openOverlay(myView,ModalityLevel.LIGHT);

Feedback

DX Core