A modal view lets you open a ViewModel as a dialog that the user must close with OK or Cancel before continuing in the view that opened it. Use it when the user must make and confirm a focused choice, such as selecting a buyer from a list.

Use a modal view

Create a ViewModel action that brings up another ViewModel, then mark that action as modal.

1. In MDriven Designer, open the ViewModel that should contain the action.
2. Create or select the ViewModel action that opens the target ViewModel.
3. Set Bring Up View Model to the ViewModel you want to show.
4. Select Is Modal.
5. Enter an Enable Expression For Modal Ok. This OCL expression determines whether the user can press OK.
6. Optionally enter an Expression After Modal Ok. This expression runs in the calling ViewModel after the user presses OK.
7. Save the model and test the action in your prototype or deployed application.

When Is Modal is selected, the target ViewModel opens on top of the calling view. The user cannot continue with the calling view until they choose OK or Cancel.

Configure the OK button

A modal action has an Enable Expression For Modal Ok. The expression is evaluated in the context of the ViewModel displayed in the modal dialog. The result must be true before the user can press OK.

Use this expression to require a valid selection or required input before accepting the dialog.

Scenario	Example enable expression	Result
Allow OK without a condition	true	The user can press OK immediately.
Require a selected car in a seeker	vSeekerResult->notempty	OK is enabled only when the search result has a selection.
Require a selected car dealer	vCurrent_CarDealer->notempty	OK is enabled only when a car dealer is current in the modal ViewModel.

For example, a CarSeeker dialog can use vSeekerResult->notempty. The user searches for cars and selects a row; until a result is selected, the dialog's OK button remains unavailable. See Training:Bootcamp:Chapter 6 for this picker exercise.

Use the value returned from the modal view

Expression After Modal Ok runs only when the user presses OK. Use it to apply the choice made in the modal ViewModel to the ViewModel that opened the dialog.

The calling ViewModel can access values from the accepted modal dialog through modal-result variables. For example, a DocumentForSales view can open a CarDealerPicker dialog and set its buyer after the user confirms a dealer:

vCurrent_DocumentForSales.Buyer:=vModalResult_vCurrent_CarDealer

In this example:

• vCurrent_DocumentForSales is the current document in the calling ViewModel.
• vModalResult_vCurrent_CarDealer is the car dealer selected in the modal ViewModel when the user pressed OK.
• The assignment is not performed when the user presses Cancel.

This pattern keeps the choice in the dialog until the user explicitly accepts it. For the full CarDealerPicker example, see Training:Bootcamp:Chapter 17.

Example: pick one or more people

A modal view is appropriate when the user needs to browse a potentially large list before confirming a selection.

1. Create an AllPersons ViewModel that lists Person instances.
2. Add a ViewModel action, for example Pick tenants, to the view that owns the tenant relationship.
3. Set Bring Up View Model to AllPersons.
4. Select Is Modal.
5. Set Enable Expression For Modal Ok to an expression that verifies that the modal view has a selection, such as the selected-person collection being non-empty.
6. In Expression After Modal Ok, update the calling view using the selection returned from the modal view.

The user can search and select people in the dialog, then press OK to return the selected value or values to the calling view. If the user cancels, the calling view does not perform the post-OK action.

Modal view or PopUp?

Choose the interaction based on whether the user must make a decision.

Use	Modal view	PopUp
Primary purpose	Require the user to accept or cancel a decision.	Show additional information or compact interaction near the current view.
Header and dialog buttons	Has a header and OK/Cancel buttons.	Has no header or OK/Cancel buttons.
Dismissal	The user closes it with OK or Cancel.	The user can dismiss it by clicking outside the popup.
Changes	Apply follow-up work through Expression After Modal Ok when the user accepts.	Changes are submitted to the underlying view; implement any cancel behavior on the underlying view.
Example	Select a buyer and confirm the selection before assigning it to a sales document.	Show more details that do not fit in the current layout.

Use a modal view when continuing without a clear choice would be incorrect. Use a PopUp when the user needs temporary supporting information and should be able to dismiss it without a confirmation decision.

In-place popup alternative

For lightweight content defined within one ViewModel, use an in-place popup rather than opening a separate modal ViewModel. Place a button and add a nesting to that button; the nesting content renders as a popup when the user presses the button. This is a PopUp pattern, not a modal accept-or-cancel workflow. See Documentation:PopUp action.

Design guidance

• Give each modal dialog one focused task. For example, use a picker dialog to select a buyer rather than combining selection, editing, and unrelated navigation.
• Make the OK enable expression describe the minimum valid state. A picker normally requires a selected item; a form may require a required value.
• Put work that must occur only after confirmation in Expression After Modal Ok. Do not rely on it for Cancel behavior because it does not run when the dialog is cancelled.
• Use a non-modal navigation action when the user should move to another view and continue working there without a forced return.
• Test both paths: press OK with a valid selection and press Cancel. Verify that only the OK path updates the calling ViewModel.

See also

• Documentation:PopUp action
• Documentation:ViewModel
• Documentation:Part 10 MDriven Designer Overview. Actions and navigation
• Training:Bootcamp:Chapter 6
• Training:Bootcamp:Chapter 17