Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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.
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.
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.
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.
Non-modal: The overlay has no curtain and does not block interaction with the part of the interface it covers. Notifications use this.
Classes that can host overlays implement the
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
You probably do not need to call
openOverlay yourself because there are convenience methods for showing messages:
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:
AlertCallbackwith an optional implementation of method
openNotificationtakes an optional
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
SubAppContext via dependency injection.
UiContext interface provides a way to get an
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.
Here are a few code examples that you can adapt to suit.
ModalityLevelas the second parameter:
myOverlay = subAppContext.openOverlay(myView,ModalityLevel.STRONG);
myOverlay = subAppContext.openOverlay(myView,ModalityLevel.LIGHT);
myOverlay = subAppContext.openOverlay(myView,ModalityLevel.NON_MODAL);