You can make an individual ViewModel open in read-only mode so users can search, navigate, and inspect data before they deliberately enter write mode.
What per-ViewModel read-only mode does
Per-ViewModel read-only mode is a framework-backed editing state controlled by the special Boolean ViewModel variable vSysReadOnlyMode. When the variable is present, the ViewModel opens with vSysReadOnlyMode set to true.
While the mode is active, MDriven disables controls and actions that are determined to change persistent data. Controls that do not change persistent data remain available. This means a user can, for example, search for a customer or navigate to a related object without first entering write mode, while an action that changes a persistent attribute is disabled.
The framework combines vSysReadOnlyMode with the ViewModel's ExternalReadOnlyExpression using OR logic. This is the same expression area used by AccessGroup View-Enable expressions. If either rule requires read-only behavior, changes to persistent data are locked.
Add read-only mode to a ViewModel
- Open the ViewModel in MDriven Designer.
- Add a Boolean ViewModel variable named
vSysReadOnlyMode. - Save and run the application.
- Open the ViewModel. The framework sets
vSysReadOnlyModetotrue, so the view starts in read-only mode. - Use the read-only switch beside Save and Cancel to change between read-only and write mode.
After Save and after Cancel, the framework changes the mode from false back to true. The next editing operation therefore requires the user to enter write mode again.
Example: protect a customer details page
Suppose a ViewModel shows a customer's name, address, and orders. Add vSysReadOnlyMode:Boolean to the ViewModel.
When the user opens the page:
- They can inspect the customer and navigate among related orders.
- Attribute editors that would update the persistent customer are read-only.
- An action that creates or deletes a persistent object is disabled.
- The user selects the read-only switch to enter write mode before changing the address.
- After Save or Cancel, the ViewModel returns to read-only mode.
The Lock/Unlock switch
When vSysReadOnlyMode is present, the framework places a special Lock/Unlock button alongside Save and Cancel. In Turnkey, its default text is Write, meaning âenter write mode.â
To influence or translate that text, create a global action with the framework action:
ExecuteFrameworkRuntimeActionRT.ReadOnlyModeToogle
Use this framework action for the action that changes the read-only state. Do not implement a separate editing-state variable; the framework detects and applies vSysReadOnlyMode.
How MDriven decides what to lock
MDriven distinguishes operations that affect persistent data from operations that are transient. This enables read-only mode to keep benign operations available.
| Operation | Typical result while read-only mode is active |
|---|---|
| Search or apply a transient filter | Available |
| Navigate to another ViewModel without persistent side effects | Available |
| Edit a persistent attribute | Disabled or read-only |
| Create or delete a persistent object | Disabled |
| Run an action that assigns to persistent data | Disabled |
For OCL expressions, MDriven checks whether the resulting element belongs to the model and is persistent. For action expressions, MDriven treats an action as affecting persistent data when it creates or deletes a persistent class, changes a persistent member with a modifying operator, or calls a method on a persistent class that is not marked IsQuery.
For the complete rules and the relationship to AccessGroups, see Documentation:AccessGroups, InterestGroups and ViewModel-Enable.
Override the persistence-effect deduction
The framework normally deduces whether a control or action affects persistent data. Use the tagged value WillEffectPersistedDataOverrideValue when that deduction must be overridden.
You can apply this tagged value to:
- a ViewModel column;
- a context action (ViewModel action);
- a class action.
Use an override only when you know the automatic classification does not describe the operation correctly. For example, if an action is classified as data-changing but it is intended to remain available in read-only mode, set the override on that action rather than changing the overall ViewModel mode.
Enable read-only mode across the application
You can make read-only mode the default for the whole application by setting:
SysMDrivenMiscSettingsSingleton.GlobalReadOnlyMode = true
When global read-only mode is enabled, exclude a specific ViewModel by setting this tagged value on that ViewModel:
SysReadOnlyModeSkip=true
Use this exclusion for a ViewModel that must not follow the application-wide read-only behavior.
Design considerations and gotchas
Read-only mode is not access control
Per-ViewModel read-only mode helps users avoid unintended edits. It does not replace authorization rules. Use AccessGroups and ViewModel-Enable when access depends on a user's role or other authorization condition.
For example, use an AccessGroup expression to prevent unauthorized users from changing financial data at all. Use vSysReadOnlyMode when authorized users should review data before choosing to edit it.
Cell-level read-only has separate rules
A ViewModel column's regular ReadOnlyExpression is evaluated in the ViewModel root context. It cannot provide a different result for every row in a list or grid. For per-cell behavior, use the <Name>_ReadOnly sibling-column pattern described in HowTos:Implement Cell Level ReadOnly in ViewModelColumns.
When global read-only mode is active, the runtime can rewrite an expression such as vReadOnly to vSysReadOnlyMode or (vReadOnly). Do not expect a displayed <Name>_ReadOnly checkbox to remain editable in that situation: the rewritten expression is not mutable in the user interface.
For editable-grid requirements and client-specific settings, see Documentation:Edit in Grid.
Visibility and read-only are different
Read-only mode prevents changes; it does not need to hide the control. If a field should disappear when it is read-only, configure its visibility separately. FollowEnable can make a column's visible expression follow the negation of its read-only expression, avoiding duplicate expressions.
Toolbar placement
If your ViewModel uses toolbar mode, the read-only switch is part of the group of editing controls with Save and Cancel. Toolbar mode also uses the distinction between safe actions and actions that change data when deciding action placement.