ViewModel actions let you add an action for users working in one specific ViewModel; use them when the action depends on what is focused or selected in that view.
Contents
What a ViewModel action acts on
A ViewModel action belongs to a single view. Unlike a Class action, it is not an action on one instance of a class. Therefore, the action does not have a self object.
Instead, the ViewModel provides variables that describe the user’s current interaction with that view:
| Variable pattern | Meaning | When to use it |
|---|---|---|
vCurrent_
|
The object currently focused in the corresponding ViewModel nesting. | Act on the row, item, or object that the user currently has focus on. |
vSelected_
|
A collection of the objects selected by the user in a grid, for the corresponding ViewModel nesting. | Apply an operation to several selected rows. |
The suffix identifies the relevant ViewModel nesting. Use the variable for the nesting where the user makes the focus or selection.
Choose the right action type
Use the action type that matches where and how users should be able to run the action.
| Action type | Use it when | Example |
|---|---|---|
| Global action | The action belongs in the main menu and often opens a view. | Open an un-rooted seeker view to find objects. |
| Class action | The action should be available whenever a user works with an instance of a particular class. | Perform an operation on the current instance of a class. |
| ViewModel action | The action is meaningful only in one particular ViewModel and depends on that view’s focus or grid selection. | Process the rows selected in a grid in one view. |
Work with current focus
Use a vCurrent_ variable when the action needs one object: the object that currently has focus in the view.
For example, a view may contain a nested list of items. A ViewModel action for that view can use the corresponding vCurrent_ variable to work with the item on which the user is currently focused. Because the action is view-specific, the same action is not automatically available everywhere that class appears.
Do not write logic that expects self in a ViewModel action. Select the appropriate vCurrent_ variable instead.
Work with multiple selected rows
Use a vSelected_ variable when the user can select multiple items in a grid. The variable is a collection for the corresponding ViewModel nesting.
For example, if users select several rows in a grid, a ViewModel action can use the relevant vSelected_ collection to apply the action to those selected objects. This differs from current focus: vCurrent_ identifies one focused object, while vSelected_ represents the grid selection.
Before you test
- Define the ViewModel that will contain the action. A ViewModel is a perspective on model information and is typed to a class; it can be rooted in an instance or un-rooted. See Define Views.
- Add the ViewModel action for the view where users need it.
- Identify whether the action should use the focused object (
vCurrent_) or the selected grid objects (vSelected_). - Validate the model. The model must be clean, with no validation errors, before you start the Prototyper or deploy it. See Verify.