You can use these built-in and convention-based variables in a ViewModel to act on the userâs current focus, inspect the running ViewModel, and adapt a Turnkey Angular view to the client viewport.
Overview
A ViewModel has predefined variables supplied by the framework. The variables available to you depend on how the ViewModel is used. In particular, cursor variables are intended for cursored user interfaces; a ViewModel used without a user interface, such as for reporting or an API scenario, can have different available variables.
Use the variables shown by the OCL or Action Editor for the expression you are editing. The editor reflects the variables available in that context.
| Variable or variable pattern | What it represents | When to use it |
|---|---|---|
vCurrent_<NestingName>
|
The object currently focused or last clicked by the user in the named ViewModel nesting. | Use it when an action or expression must act on the current item in a list. |
vSelected_<NestingName>
|
A collection of selected objects for the named nesting. | Use it when a grid permits multi-selection and an action must process every selected item. |
selfVM
|
The running ViewModel. | Use it in Action Language expressions that need to execute an action, re-execute a query plan, inspect changed objects in the view, or work with view-related access groups and security. |
vClientScreenWidth
|
The client viewport width when the variable exists in the ViewModel. | Use it in a Turnkey Angular ViewModel to make view-level decisions based on viewport width. |
vClientScreenHeight
|
The client viewport height when the variable exists in the ViewModel. | Use it in a Turnkey Angular ViewModel to make view-level decisions based on viewport height. |
vIsMobileDevice
|
Indicates whether the device is seen as a mobile device, when the variable is defined. | Use it only after you have declared the variable in the ViewModel. |
Work with the current and selected items
vCurrent and vSelected are maintained for each level of a ViewModel nesting. Their postfix comes from the nesting name, and their types match that nesting.
For example, if a nesting is named Order, use the corresponding cursor variables:
-- Act on the currently focused Order
vCurrent_Order
-- Process the collection selected in the Order grid
vSelected_OrdervCurrent_ identifies one current object. vSelected_ identifies a collection. The selection collection is relevant when multi-select is enabled in a grid.
Auto-select behavior
WebUI DataGrids automatically select the first row when the list does not use MultiSelect. With MultiSelect, the default is not to auto-select the first row. Set Nesting.AutoSelectFirstRow explicitly to true or false when the initial current row matters to your ViewModel behavior.
Use `self` and `vCurrent_` for different purposes
self is the object being rendered where the expression appears. It is local to that expression. By contrast, vCurrent_<NestingName> is the current object for the named nesting across the ViewModel.
In a master-detail view of Years, Months, and Days, use the relationship from self while rendering each branch. Do not use a parent listâs vCurrent_ inside every row merely to render that rowâs child list. If the user selected 2015, vCurrent_ evaluates to 2015 for every Year row, including 2014 and 2016. That can cause unnecessary and incorrect data updates even if the visible branch appears correct.
Use vCurrent_ when a list is intentionally filtered by a selection in another list, or when an action needs the userâs current focus. For a full master-detail explanation and the effect on data sent to Turnkey clients, see Documentation:How to use vCurrent and âselfâ correctly in viewmodels.
Use cursor variables in actions
ViewModel actions act on one view rather than on a class object. Therefore, actions use variables beginning with vCurrent_ to identify the focused object, and vSelected_ collections to identify multiple selected objects.
For example, an action invoked from an Order grid should use vCurrent_Order when it applies to the focused Order, and vSelected_Order when it applies to every checked Order.
Access the running ViewModel with `selfVM`
Use selfVM when an OCL or Action Language expression needs the ViewModel itself rather than an object rendered in a nesting.
Examples of ViewModel-level work include:
- Executing a ViewModel action.
- Executing persistent-storage SQL.
- Re-executing the query plan.
- Finding objects changed in the view.
- Examining or executing view-related access-group or security behavior.
This differs from self: self is the current rendered object, while selfVM references the running ViewModel.
Use viewport variables in Turnkey Angular
The Turnkey Angular client sets vClientScreenWidth and vClientScreenHeight when variables with those names exist in the ViewModel. This lets you implement viewport-dependent ViewModel logic, similar in purpose to media queries but evaluated at the ViewModel level instead of in CSS.
- Add a ViewModel variable named
vClientScreenWidthwhen your view needs the viewport width. - Add a ViewModel variable named
vClientScreenHeightwhen your view needs the viewport height. - Use the values in the ViewModel logic that chooses what to show or how to arrange the view.
For example, a view can use vClientScreenWidth as an input to decide whether a secondary area should be shown in the current layout. The exact width threshold is part of your applicationâs design.
Read VClientScreenWidth and VClientScreenHeight for the client-specific behavior.
`vIsMobileDevice`
If you define vIsMobileDevice in the ViewModel, it indicates whether the device is seen as a mobile device. Use this value for ViewModel behavior that differs between mobile and non-mobile devices.
For example, you can use the value as a condition for whether a mobile-oriented part of a view is shown. Define the variable before relying on it in an expression.
`vCurrent_Root`
vCurrent_Root follows the vCurrent_<NestingName> cursor-variable pattern for a nesting named Root. Its value is the current object for that nesting. In a rooted ViewModel with one root object, that current object can remain the same and correspond to the root object.
Do not assume that vCurrent_Root is the same as self in every expression. self always depends on the ViewModel class and expression location; vCurrent_Root identifies the current object of the Root nesting.
Availability and initialization
Cursor variables are designed for cursored ViewModels. You can turn off vCurrent and vSelected variables with the applicable tagged value. In API and report scenarios, cursor variables are often not used, and the available variable set can differ.
You can also create your own ViewModel variables, for example to retain a reference to an object the user is working on. An initial variable value cannot be an expression. Initialize a variable that needs an expression in an init action that runs once, such as a periodic action configured to run once, or in the OnShow expression of the action that navigates to the view.
Do not confuse ViewModel variables with Server Wide Variables. Server Wide Variables are declared in MDrivenServer and made available to a ServerSide ViewModel by adding a ViewModel variable with the same name.