You can configure an action to change model data, control when users can run it, open a ViewModel, return a modal selection, or invoke a framework-level command; this page is for MDriven Designer modelers defining those behaviors.

Choose the action context

An action expression always runs in a context. The context determines which objects and variables the expression can address.

Action type	Expression root and available values	Typical use
GlobalAction	There is no current object. Use model-level expressions that start from a class, such as X.allinstances or X.Create.	Open an un-rooted seeker or browser from the main menu.
ContextAction	The action can use variables supplied by the ViewModel context. The current value is named vCurrent_TheViewModelClassName.	Run an action for the object the user selected in a grid.
ClassAction	The action is rooted in an object of its class. Use the OCL identifier self for that object.	Act on the displayed or selected instance, such as a rental contract.

For example, a ClassAction on RentalContract can use self to reach its attributes and associations. A ContextAction in a ViewModel can use a current variable such as vCurrent_RentalContract. Current variables follow the user's selection in ViewModel grids, so the action can operate on the object the user selected.

You can navigate associations and use attributes for as many steps as the model requires. If the current rental contract has an assigned car, an expression can start at the current contract and navigate to that car.

For where each action type appears in the user interface, and how to opt actions in or out of a ViewModel, see Training:Available Actions. For GlobalActions and the main menu, see Training:Global actions.

Execute an expression

ExecuteExpression uses EAL

ExecuteExpression is an Extended Action Language (EAL) expression. EAL can change the domain objects and variables in its context. Use the button beside the expression to open the EAL editor.

Use EAL when an action must perform work. For example, EAL uses := as the assignment operator:

vIntHolder := Integer.Parse(vANewVariable)

This assigns the parsed value to vIntHolder. In contrast, an OCL expression observes and calculates; it does not assign or otherwise change data. The action-language exercises in Training:Bootcamp:Chapter 4 show how to test expressions and inspect variable values.

Work from the right root

1. For a GlobalAction, start from a model class. For example, use operations that begin with X, such as X.allinstances or X.Create.
2. For a ContextAction, use the current context variable when the operation concerns the object selected by the user.
3. For a ClassAction, use self to operate on the object of the action's class.
4. Use the EAL editor to validate the expression in the action's actual context.

Control whether an action is available

EnableExpression determines whether the user can execute the action. It uses OCL rather than EAL.

An EnableExpression must:

• Have no side effects. It must not create, delete, update, or assign values.
• Evaluate to a Boolean value: true or false.
• Use the same action context and reach the same context variables as the ExecuteExpression.

For example, enable a delete action only when its ClassAction object is in the Deletable state:

self.oclIsInState(#Deletable)

When the expression evaluates to false, the action is not executable. Keep business changes in ExecuteExpression and use EnableExpression only to decide availability.

Open a ViewModel

An action can open a ViewModel-defined UI by setting BringUpViewModel. The action can also provide the ViewModel's root object through ViewModelRootObjectExpression.

1. Select the ViewModel to open in BringUpViewModel.
2. Set ViewModelRootObjectExpression to an expression that returns the object that should become the opened ViewModel's root object.
3. Leave the root-object expression empty when the opened ViewModel does not need a root object.

An empty root object is appropriate for a seeker that searches persistent storage rather than displaying one preselected object. Global actions commonly open these un-rooted seekers or browsers; see Training:Global actions.

Return a value from a modal ViewModel

Set ViewModelIsModal when the opened ViewModel must behave as a dialog that the user closes with OK or Cancel. The WECPOF runtime adds OK and Cancel buttons at the bottom of that window.

User choice	Result
Cancel	The modal window closes. No after-modal expression runs.
OK	The modal window closes and the runtime executes ExpressionAfterModalOk, if defined.

ExpressionAfterModalOk is an EAL expression. It has access to the calling action's context in the same way as ExecuteExpression. It also receives variables from the ViewModel that is closing. Those returned variables are prefixed with vModalResult_ to prevent name collisions with variables in the calling context.

Example: seek, pick, and assign a car

Use a modal picker when a rental contract can be assigned to one of many cars. A ComboBox is a poor fit when the user must find a car among 500 or more candidates.

1. Add a ContextAction to the rental-contract ViewModel.
2. Set BringUpViewModel to Free-Car-Seeker-ViewModel.
3. Select ViewModelIsModal.
4. In the seeker ViewModel, expose the selected car as its current picked-car value.
5. Set ExpressionAfterModalOk to assign the selected modal result to the calling rental contract:

vCurrent_RentalContract.AssignedCar:=vModalResult_Current_PickedCar

1. Run the action, search for and select a car, then choose OK. The after-modal expression assigns the selected car. Choose Cancel to close the seeker without making that assignment.

The same pattern can assign a customer to a rental contract. For a working prototyping example of modal customer and car selection, see Training:Prototyping.

Use a framework action

A Framework Action invokes behavior at a level other than your model. When you select a framework action, the other action expressions do not apply.

Framework action	Behavior
Save	Saves created, deleted, and updated objects through the persistence mapper used in the EcoSpace or Gaffr.
Refresh	Calls refresh on the persistence mapper when that mapper supports Refresh. A sync server must be set up to allow it.
Undo / Redo	Calls undo or redo on the EcoSpace. The WECPOF runtime creates a new undo block every other second when there are changes.
Exit	Quits the WECPOF application.

The standard framework actions are commonly configured as GlobalActions. Training:Global actions describes the standard action set and how to restore it if it has been removed.

Configure an action in order

Use this order to avoid mixing calculation, data changes, and navigation:

1. Choose the action type and confirm its context.
2. Define an EnableExpression when availability depends on the current object or selection.
3. Add an ExecuteExpression when the action must change data or variables.
4. Set BringUpViewModel and ViewModelRootObjectExpression when the action opens a ViewModel.
5. Set ViewModelIsModal and ExpressionAfterModalOk when the opened ViewModel must return a selection.
6. Select a Framework Action instead when the action must save, refresh, undo, redo, or exit; do not configure the other expressions for that action.
7. Run the action in the prototype and verify both the enabled state and the resulting data. See Training:Prototyping.

See also

• Training:Available Actions
• Training:Global actions
• Training:Bootcamp:Chapter 4
• Training:Bootcamp:Chapter 5
• Training:Prototyping