You can use this session to make a MDriven Turnkey application show relevant actions, group global actions into menus, and communicate object rules through class constraints; it is for modelers working in MDriven Designer.
Watch the Session 3 walkthrough.
What you will configure
This session covers four related model-design tasks:
| Task | What you achieve | Example |
|---|---|---|
| Opt out an action from a ViewModel | Remove an action where it is not useful or where it is already available elsewhere. | Remove a second Edit One Car or Create Car action from an All Cars view. |
| Group global actions | Build a menu bar that contains logical submenus rather than a flat list of global actions. | Put global view actions under a Views menu and a brand-management action under ValueStores. |
| Add a class constraint | Tell users when an object does not follow a rule in the model. | Require a Car to have a registration number. |
| Set DefaultStringRepresentation | Choose the text used when an object is shown as a string in the UI. | Show a Car by its registration number rather than an automatically generated name. |
Opt out actions that do not belong in a view
An action can be available because the current ViewModel contains an object of the action's class. This can cause the same action to appear more than once. For example, an All Cars ViewModel may expose an Edit One Car action from the selected Car and also expose a similar action in another part of the UI.
Opt out an action on the ViewModel where it adds no value. Opting out changes availability in that location; it does not remove the action from the model.
- Open the model in MDriven Designer.
- Open the ViewModel that shows the unwanted or duplicated action, for example All Cars.
- Locate the action in the ViewModel's action presentation.
- Use the arrow control shown for that action to opt it out from the current location.
- Repeat for actions that are redundant in the view. For example, in an Edit One Car view, opt out Edit One Car when the view already edits that Car.
- Run a model check after changing expressions or model rules.
- Upload the model.
- Refresh the Turnkey application and verify that each remaining action is available where users need it.
Choose the right action locations
Keep an action where the user has the required context. If an action operates on a Car, show it from a view that has a relevant Car. Remove it from a view where it duplicates another command or would make the menu unclear.
This is UI organization, not access control. To control which users can use actions, see Documentation:Turnkey Session 5: How to Access the Logged in User. AccessGroups in the Documentation:MDriven Turnkey Series.
Global actions can appear directly in the Turnkey menu. As the application grows, group them into meaningful submenus.
- Identify the global actions that should be grouped.
- Assign related actions to a menu group in MDriven Designer.
- Use a group such as Views for global view-navigation actions.
- Create a domain-oriented group when appropriate. For example, place Manage Brand in a ValueStores group.
- Upload the model and refresh the application.
- Verify that the global actions now appear in their intended submenus.
Use group names that describe the user's task. For example, ValueStores communicates that the menu contains maintenance actions for stored values such as brands. Do not create a submenu for one action unless that organization is meaningful for your application.
Add class constraints
A class constraint is a rule on every instance of a class. Turnkey presents broken constraints in views so users can see which rules their data must satisfy.
A constraint has:
- A name that identifies the rule.
- A description that tells the user what to correct.
- An OCL expression that evaluates the rule.
- A severity, such as a required rule or a warning.
The expression must evaluate to true when the constraint is satisfied. If it evaluates to false, the constraint is broken.
Example: require a registration number
For a Car class, add a constraint named Must have registration number.
| Constraint part | Example value |
|---|---|
| Name | Must have registration number |
| Description | Must have registration number |
| Expression intent | The Car's registration-number attribute is not null or empty. |
When a Car has no registration number, Turnkey shows the broken constraint. Entering a registration number makes the expression true and removes the broken-constraint indication.
Example: communicate a recommended brand
You can also make a rule informational rather than mandatory. For example, add a constraint stating that a Car Should have brand, set its severity to a warning, and use an expression whose intent is that self.Brand is not empty.
This lets the UI tell the user that the brand is missing without presenting the rule as a mandatory requirement. The constraint description can incorporate the referenced object's description when that makes the message clearer.
Check OCL before you upload
When you enter an OCL expression manually, run the model check to find invalid or broken expressions before uploading the model. An expression that refers to an attribute or association must use the names in your model.
For an introduction to OCL expressions and their use with model objects and collections, see Turnkey Session 7: Expressions.
Show objects with DefaultStringRepresentation
DefaultStringRepresentation defines the text used when an object is rendered as a string. Set it on the class so that lists, action labels, and constraint messages identify objects with useful domain text.
For example, set the Car class DefaultStringRepresentation to its registration number. A Car that has registration number SomeNumber1 can then be presented as SomeNumber1 instead of a less useful generated representation. The same representation can appear in context such as an Edit One Car view or a constraint message.
Choose a representation that users recognize and that is meaningful for the class. For Car, a registration number is appropriate when it identifies the vehicle in the application.
Hide a constraint in a specific ViewModel
A class constraint applies to the class, but you can opt it out from a particular ViewModel when that ViewModel should not show that constraint. For example, after adding a Should have brand warning on Car, opt it out from All Cars if that overview should display only the registration-number requirement.
- Open the target ViewModel, such as All Cars.
- Locate the class constraint in the ViewModel presentation.
- Use the opt-out control for the constraint.
- Upload the model and refresh Turnkey.
- Confirm that the constraint remains defined for Car but is no longer shown in that ViewModel.
Use this carefully. Hiding a constraint from a view does not change the underlying class rule; it only changes what that view presents to the user.
Class constraints and ViewModel validation
Class constraints express rules for instances of a class, such as every Car having a registration number. ViewModel validation is validation designed for a particular ViewModel. Use a class constraint for an object-level rule that should follow the object, and use ViewModel validation when the rule depends on the specific interaction or view.
Verify your changes
After each set of changes:
- Run the model check, especially after editing OCL expressions.
- Upload the model.
- Refresh the Turnkey application.
- Test an object that breaks the rule and an object that satisfies it.
- Check that actions appear once, in the intended menu or context.
- Check that the object text shown in the UI matches the configured DefaultStringRepresentation.