You use navigation to let users open the right ViewModel for a business object, such as opening a selected customer from a customer list in a detail view.

Navigation in MDriven

In MDriven, an Action can open a ViewModel. The Action determines which ViewModel to show and, when the target ViewModel is rooted, which object becomes its root.

A rooted ViewModel is a ViewModel that displays or works with one specific object. For example, a Customer detail ViewModel can be rooted in one Customer, so its fields show that customer's name and other attributes.

The usual navigation flow is:

1. Show a browser or list of existing objects.
2. Let the user select an object.
3. Run an Action that opens a detail ViewModel.
4. Set the detail ViewModel's root to the selected object.
5. Let the user navigate onward to related objects where needed.

This pattern gives users a starting point for finding existing information and a focused view for changing or inspecting one object.

Choose the target ViewModel and root

When you configure an Action for navigation, decide both of the following:

Decision	What it controls	Example
Target ViewModel	The view the Action opens.	An Action opens Customer detail.
Root object expression	The object supplied to a rooted target ViewModel.	The expression evaluates to the customer selected in Customer browser.

Do not confuse the two. Selecting a target ViewModel does not supply an object to it. If the target requires a root object and its root object expression is empty, the ViewModel can open with a null root.

Example: open a new object

A global Action is an Action shown in the main menu. It can open a ViewModel and create the object that will be its root.

For a ViewModel rooted in Class1, a root object expression such as the following creates a new root object when the Action runs:

Class1.create

The Action can then open the Class1 ViewModel with the newly created object as its root. Repeating the Action creates additional objects; it does not provide a way to find the objects created earlier. For that, provide a browser ViewModel.

Example: open an existing object from a browser

A browser ViewModel shows a collection of existing objects. Add an Action in the context of an item in that browser, set its target to the detail ViewModel, and use the current selected object as the root object expression.

For example, when a user selects a Class1 row in a browser:

1. Run the item's Action.
2. Open Class1 object, the detail ViewModel.
3. Set the target root to the selected Class1 object.

The detail ViewModel now shows the object the user chose. A Back command can return the user to the browser, where they can select another object.

Mark rooted ViewModels correctly

If an Action sets a ViewModel root object, configure the target ViewModel to require a root object. MDriven Designer reports a model warning when an Action sets a root but the target ViewModel does not require one.

This check helps keep the model consistent:

• A ViewModel that shows details for one object should require a root object.
• A browser or other top-level ViewModel that does not need one should not require a root object.
• An Action that opens a non-rooted ViewModel does not need to provide a root object.

A class-level ViewModel can be available at a level where no particular object is assigned. In that situation, its root can be null unless the ViewModel is configured to require a root and the Action supplies one.

Use Execute expression on show for opening context

An Action can also have an execute expression on show. MDriven evaluates this expression when the target ViewModel is shown.

Use this expression to initialize view context or values that depend on where the user came from. In this expression, the receiving ViewModel has access to its root through its current-root variable, and vSender represents context from the Action that opened the view.

For example, an expression can update an attribute when a detail ViewModel opens. If the expression increases an attribute by one, reopening that ViewModel runs the expression again and increases the value again.

Use this behavior deliberately:

• Use the root object expression to supply the object that the target ViewModel is rooted in.
• Use execute expression on show to establish opening context or perform intended work each time the view is shown.
• Do not use execute expression on show as a replacement for the root object expression.

See Documentation:EAL for executable Action language and Documentation:OCL for expression language concepts.

Prefer explicit, static navigation

Define the target ViewModel directly on the Action whenever possible. Direct references make it easier to understand the navigation paths in the model.

For conditional navigation where a static target ViewModel reference is not sufficient, MDriven provides selfVM.Navigate(root,Class.ViewModels.YourTarget). This switches the view and permits expressions for both the root and target ViewModel.

selfVM.Navigate(root,Class.ViewModels.YourTarget)

Use dynamic navigation as a last resort. Logic that chooses a ViewModel dynamically makes it harder to statically see what the application does. For details and the documented syntax, see Documentation:OCLOperators Navigate.

Build navigation around user tasks

Design navigation from the user's starting task rather than only from the model structure. A practical sequence is:

1. Create a browser ViewModel for objects users need to locate.
2. Add item Actions that open a detail ViewModel rooted in the selected object.
3. Add Actions from the detail ViewModel to related objects only when users need to continue the task.
4. Check model warnings and correct mismatches between Actions and the target ViewModel's root requirement.
5. Test both paths: creating a new object and opening an existing object.

For example, a user can browse all Class1 objects, select one to open its object view, edit an attribute, and return to the browser. This is more useful than exposing only a global Action that always creates a new Class1.

Action names affect what users see and how they understand the available task. See Training:Action names for naming guidance.

Navigation in different user interfaces

The Action-to-ViewModel pattern describes navigation at the model level. Runtime implementations can have additional behavior.

Runtime scenario	Guidance
Turnkey and MVC to Angular navigation	MVC-to-Angular navigation requires two EcoSpaces so action continuity is retained when the MVC EcoSpace is handed to the streaming API. See Documentation:Serverside Turnkey and MVC functioning.
WPF Turnkey application	MDriven Turnkey can be used with WPF for rich desktop applications. See Documentation:WPFMahappAndGantt.

The presentation of actions and views can also depend on layout and styling. See Documentation:Layout and CSS.

Learn by building the pattern

The recommended exercise is to create one class, a detail ViewModel for that class, a global Action that opens it, and then a browser ViewModel that opens existing objects in the detail ViewModel. Verify that the detail ViewModel receives a non-null root when it is supposed to, then test any execute expression on show by opening the view more than once.

For the complete Designer walkthrough of Actions, root object expressions, and browser-to-detail navigation, see Actions and navigation or watch the walkthrough.

See also

• Documentation:Part 10 MDriven Designer Overview. Actions and navigation
• Documentation:OCLOperators Navigate
• Documentation:OCL
• Documentation:EAL
• Training:Action names