ViewModel actions let you define behavior for one ViewModel and act on the current or selected data in that view; use them when the action depends on what the user is viewing or selecting rather than being available wherever a model class appears.
What a ViewModel action is
A ViewModel action is an action whose scope is a single ViewModel. Unlike a Class action, it is not an action on one instance of a model class and therefore has no self object.
Instead, the action receives its context from the ViewModel. MDriven makes the current item and the selected items in a ViewModel nesting available through variables whose names begin with vCurrent_ and vSelected_.
Use a ViewModel action when the operation belongs to a specific screen or depends on the screen's layout, selection, or navigation context. For example, in a ViewModel that shows a grid of rental contracts, an action can use the current rental contract from that grid's vCurrent_ variable or work over the contracts selected by the user through the corresponding vSelected_ collection.
ViewModel actions compared with other actions
| Action type | Scope | Use it when |
|---|---|---|
| ViewModel action | One ViewModel | The behavior is specific to a view and uses that view's current item or selection. |
| Class action | A model class wherever that class is available in the user interface | The behavior belongs to an object of the class. A Class action has a self object.
|
| Global action | The application | The user must be able to start the action independently of a particular ViewModel. |
For the complete action model, including Global, Class, periodic, and server-side actions, see Documentation:Actions and Documentation:Application actions.
Use the ViewModel context
Current item: vCurrent_
vCurrent_ identifies the item currently focused in a ViewModel nesting. Its full variable name corresponds to the relevant nesting. Use it when an action should affect the item that currently has focus.
For example, if a user focuses one row in a rental-contract grid, an EAL expression in a ViewModel action can use that nesting's vCurrent_ variable to operate on that focused contract. The action does not use self, because it is executing in ViewModel context rather than on a class instance.
Selected items: vSelected_
When the user selects multiple items in a grid, MDriven provides the selected items in a vSelected_ collection for the corresponding ViewModel nesting. Use this collection for a batch operation.
For example, an action named ProcessSelectedContracts can use the grid nesting's vSelected_ collection to process all contracts selected by the user, rather than only the focused row.
Gotcha: Current and selected variables are tied to a ViewModel nesting. In a ViewModel with more than one grid or nested area, use the variables that correspond to the nesting containing the data you intend to act on.
Create a ViewModel action
Create the action in the ViewModel that owns the interaction.
- In MDriven Designer, open the ViewModel.
- Go to ViewModel Actions.
- Click ViewModel action.
- Double-click the new action to open the Actions Editor.
- Enter the action name and its execute expression.
- Write the expression against the ViewModel context, using the relevant
vCurrent_orvSelected_variable when the action needs focused or selected data.
Keep the action focused on the ViewModel's task. If the same behavior should be available wherever an object of a class is shown, define a Class action instead.
Put a ViewModel action on a nested ViewModel button
You can invoke a ViewModel action from an action column in a nested ViewModel.
- Add an action column to the nested ViewModel.
- Create the ViewModel action under ViewModel Actions and edit it in the Actions Editor.
- Give the ViewModel action exactly the same name as the action column.
- Return to the action column and verify that its name matches the ViewModel action name.
- Do not link the created ViewModel action to the action column. When the names match, the button works automatically and executes the ViewModel action expression.
For the full nested-button procedure and the alternative of using a Class action, see Documentation:Adding Buttons in Nested ViewModels.
Behavior in tables
ViewModel/Context actions have a limitation in web-client tables: since 2020-09-27, they are shown as disabled when placed in a table. Class actions and actions with EAL in a ViewModel continue to work in tables with their normal enabled and disabled behavior. Plan a table-row command around this limitation, or use the appropriate alternative action type. See Documentation:Web client actions in tables.
Control which actions users see
ViewModel actions are available only in the ViewModel where you define them. Class actions can appear wherever their class is shown unless you change their presentation for a view. Review and control action opt-in and opt-out behavior in Training:Available Actions.