The ViewModel Editor is where you define the data, actions, nesting, and layout hints that a ViewModel exposes for one use case; it is for MDriven Designer users designing a view of model data.
A ViewModel is not the domain model and it is not the final running user interface. It defines the information to collect and present for a particular use case. For example, a HouseView can expose a house's street name, street number, and an action to create a street without exposing every member of the House class.
Open and create a ViewModel
Open the ViewModel Editor with the ViewModel Editor button in MDriven Designer.
To create a ViewModel:
- Add a new ViewModel in the editor.
- Root it in the class that represents the main object for the use case.
- Give it a use-case-oriented name.
- Add the columns, nestings, actions, and placing hints needed by that use case.
For example, when the view starts from a House, root the ViewModel in House and name it HouseView. The ViewModel then appears under the repository's ViewModels node.
| Decision | Guidance | Example |
|---|---|---|
| Root class | Choose the object the view is about. | A house detail view is rooted in House. |
| Name | Name the ViewModel for its use case rather than using a generic name. | HouseView identifies a view of a house. |
| Exposed data | Include only the data the use case needs, including selected data reached through associations. | Include street name and street number rather than every House attribute. |
| Layout metadata | Use placing hints when you want the generated UI to have a defined arrangement. | Place address fields together in the generated UI. |
Add columns
Columns define the values and actions available from a ViewModel. In the editor, use Add column to add a column in the context of the ViewModel root.
The guided choices help you add members that are available from the root class, including members reached through navigation. You can also add a generic column. A generic column has no OCL expression until you define one.
Example: build a HouseView
Assume the ViewModel is rooted in House and House has an association named TheStreet.
- Click Add column.
- Add the House address value if the model has an Address property.
- Click Add column and navigate through TheStreet to add TheStreet.Position.
- Rename the resulting columns to names that make sense in the view, such as Address and Position.
- Add a generic column when the value requires an expression that is not supplied by the guided choices.
Column expressions use OCL. In an expression on a House-rooted column, self refers to the House object. For example:
self.TheStreet.NameIf a model change removes House.Address, update any ViewModel column that still uses self.Address. The expression is no longer valid because Address is no longer a member of House. Replace it with an expression that matches the changed model, for example self.TheStreet.Name when the street name now supplies the address information.
For detailed OCL editing and model-prototyping examples, see Documentation:OCL Editor, system prototyper and ViewModel.
Add an action column
Use Add column to add a column prepared for an action when the user must perform work from the view. The action column opens the action-language editor, where you define the expression that runs for the action.
For example, a HouseView can offer an action named CreateStreet that creates a Street and assigns it to the current House:
self.TheStreet:=Street.CreateAfter this action runs, the created Street is available to the action. Add the fields that users need in order to set values on the new Street, such as its name or position, and test the flow in the generated ViewModel UI.
Keep business rules in the model. Use the ViewModel action to expose the specific operation required by the use case, rather than making the view a replacement for model rules.
Arrange the generated UI with placing hints
Placing hints are ViewModel metadata that describe where columns should be positioned in the generated UI. Use the placing-hints matrix to arrange columns. Turn on Show the gridlines to see the grid interpretation of the current hints.
The grid is a design aid. It describes how the engine interprets the ViewModel metadata; it is not the final UI that users execute. Use it to make the intended grouping and order clear before testing the generated result.
For live editing of a running Turnkey application's UI, use Turnkey Live View rather than treating the editor grid as the final rendered application.
Test the ViewModel
Test the ViewModel against data after saving your changes and re-reading the model.
- Select an object or object set in the system prototyper.
- Choose Result as root ViewModel tree to inspect the data exposed by the ViewModel.
- Choose Result as root ViewModel UI to let the engine construct a UI from the ViewModel definition and its placing hints.
- Enter or change values as required, run actions, and save the changes.
- Revisit the ViewModel when the model changes and correct expressions that refer to removed or renamed members.
For example, after adding CreateStreet to HouseView, open a House as the root ViewModel UI, run the action, set the Street values, and save. You can then inspect the Street instances to confirm that the action created the expected objects.
Design one ViewModel per use case
A ViewModel defines a selected view of model information for consumption by a use case. Do not expose an entire class because it happens to be available. Instead, select the attributes, association paths, actions, and nested information the use case requires.
For example, a HouseView intended to register a house may need:
- Street name through TheStreet.Name
- Street number
- Street position
- An action to create a Street when no Street exists
A different use case can use a different ViewModel with a different selection of data. This separation helps keep business rules in the model while limiting what each view exposes.
Use ViewInView when the use case requires one view within another.
Inspect and maintain expressions
ViewModel columns and actions can depend on many model members. When you change the model, analyze the ViewModel to find invalid or affected expressions.
- Open the ViewModel in the ViewModel Editor.
- Click Analyze expressions in the upper-right corner.
- Review the ViewModel as a UML diagram and inspect the affected classes and expressions.
- Correct expressions, actions, or columns that no longer match the model.
See HowTos:Analyze ViewModel Classes and Expressions for this analysis workflow.
Work with variables
Expressions in a ViewModel do not always have the same context. self depends on where the expression is placed. For example, in a nested detail ViewModel class, self refers to that detail object; in an action column on the root class, it refers to the root object.
ViewModel actions commonly use variables such as vCurrent or vSelected when the action must work with the active or selected object. selfVM refers to the running ViewModel. You can inspect the variables available in a given context in the OCL Editor or Action Editor.
Do not initialize a ViewModel variable with an expression as its initial value. Initial values cannot be expressions, and model checking may not warn about this. Initialize such a value in an init action that runs once, or in the OnShow expression of the action that navigates to the view. For the complete variable rules and contexts, see Documentation:ViewModel variables.