View source for MDrivenStart:MDrivenStart ViewModelActions

ViewModel actions let you add an action for users working in one specific [[Documentation:ViewModel actions|ViewModel]]; use them when the action depends on what is focused or selected in that view.

== What a ViewModel action acts on ==
A ViewModel action belongs to a single view. Unlike a [[MDrivenStart:MDrivenStart ClassActions|Class action]], it is not an action on one instance of a class. Therefore, the action does not have a <code>self</code> object.

Instead, the ViewModel provides variables that describe the user’s current interaction with that view:

{| class="wikitable"
! Variable pattern
! Meaning
! When to use it
|-
| <code>vCurrent_</code>
| The object currently focused in the corresponding ViewModel nesting.
| Act on the row, item, or object that the user currently has focus on.
|-
| <code>vSelected_</code>
| 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.

{| class="wikitable"
! Action type
! Use it when
! Example
|-
| [[MDrivenStart:MDrivenStart GlobalActions|Global action]]
| The action belongs in the main menu and often opens a view.
| Open an un-rooted seeker view to find objects.
|-
| [[MDrivenStart:MDrivenStart ClassActions|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 <code>vCurrent_</code> 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 <code>vCurrent_</code> 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 <code>self</code> in a ViewModel action. Select the appropriate <code>vCurrent_</code> variable instead.

== Work with multiple selected rows ==
Use a <code>vSelected_</code> 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 <code>vSelected_</code> collection to apply the action to those selected objects. This differs from current focus: <code>vCurrent_</code> identifies one focused object, while <code>vSelected_</code> 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 [[MDrivenStart:MDrivenStart DefineViews|Define Views]].
# Add the ViewModel action for the view where users need it.
# Identify whether the action should use the focused object (<code>vCurrent_</code>) or the selected grid objects (<code>vSelected_</code>).
# Validate the model. The model must be clean, with no validation errors, before you start the Prototyper or deploy it. See [[MDrivenStart:MDrivenStart Verify|Verify]].

== See also ==
* [[Documentation:ViewModel actions]]
* [[MDrivenStart:MDrivenStart DefineUserActions]]
* [[MDrivenStart:MDrivenStart ClassActions]]
* [[MDrivenStart:MDrivenStart GlobalActions]]
* [[MDrivenStart:MDrivenStart DefineViews]]

{{Template:MDrivenStart_Template}}

[[Category:MDrivenStart]]