A dialog with a client-side modality curtain alone doesn’t disable the UI to which it belongs on the server side. If the dialog or its modality curtain is removed from the DOM on the client side, its parent UI remains active on the server and can be interacted with.
To fully prevent interactions with components that are underneath a modal dialog (or any modal component, for that matter), Flow has a feature called server-side modality. This feature makes Flow ignore interactions with all components that aren’t children of the modal component while it’s attached or marked as modal. Components that aren’t children of the modal component are said to be inert, that is, they aren’t available for interaction.
As server-side modality is purely a server-side security feature that only prevents interaction, it doesn’t add a modality curtain or change the visible state of the components in the UI. Adding a modality curtain should be handled by the component.
UI class provides methods that allow access to the server-side modality feature. The following Vaadin components make use of the feature: Dialog, Notification, and Login View.
Modal dialogs can be stacked on top of each other, but only the most recent is active. A modal dialog can open another modal dialog, or several modeless dialogs, which again can open modal or modeless dialogs.
|Opening a new Dialog, Confirm Dialog, or Notification when a modal Dialog is already open automatically makes the new Dialog or Notification a child of the previously opened Dialog. Closing the "parent" Dialog also closes all subsequently opened Dialogs and Notifications.|
The implementation relies on a server-side-only state tree feature called
InertData, which makes it possible to stop a component/element/state node and its children from accepting any updates from the client side.
By default, the inert state is inherited to child nodes.
However, any child can declare itself as ignoring the parent’s inert state, which means that updates are allowed for itself and its children, unless these are explicitly made inert.
This documentation is focused on the usage of the following methods of a
UI.addModal(Component) method to add a modal component to the UI or to make an attached component modal with
This makes inert all components that aren’t children of the modal component in the UI.
If you have a modal component and you add a new one with |
When the component is later removed from the UI or defined as non-modal with
setChildComponentModal(Component, false), the UI is no longer inert, unless there was another modal component underneath the removed component.
// Add a modal component, and make the rest of the UI inert UI.getCurrent().addModal(component); /* other code*/ // Remove the modal component. The UI is no longer inert. UI.getCurrent().remove(component);
To make an already-added component modal, use
// Make a component modal, and make the rest of the UI inert UI.getCurrent().setChildComponentModal(component, true); /* other code*/ // Make the component non modal. The UI is no longer inert. UI.getCurrent().setChildComponentModal(component, false);
To add a component to the currently active modal component, use
UI.addToModalComponent(Component), which adds the component under the current modal component.
This is intended to be used with components that aren’t added as part of a layout, such as a dialog, so that they are interactive when a modal component opens up an overlay component.
To check if there is a defined modal component, use
This is usually needed if a new component is added.
To be usable, it needs to be added under the modal component.
When there is no active modal component, calling |
An example project that demonstrates these APIs in action can be found here. This demo application contains the following views to present some possibilities with server modality:
Dialog Modality Showcase: Basic usage and comparison between modeless vs. client modal vs. server modal for dialogs.
Grid With Large Dataset: Shows a server-modal dialog on the view while a long-running process is in progress.
Modality on Top of Dialog: Shows how to use
UI#addToModalComponent()to add a modal component to the current modal component.