View source for Documentation:Class actions

You can define a '''class action''' in MDriven Designer when an operation belongs to an object in the model and must be available wherever that class is shown.

A class action is an [[Documentation:Actions|action]] whose context is an instance of one class. It works from the model object itself, rather than from the state of a particular [[Documentation:ViewModel|ViewModel]]. For example, a <code>ShowDetails</code> action on <code>Person</code> can be made available in every view that presents a <code>Person</code>.

[[File:Class Actions - Image 1.png|frameless|84x84px]] 
== When to use a class action ==
Use a class action when the action:

* operates on the current object of a class;
* does not need the current selection, focus, or other state of one specific ViewModel; and
* should be reusable wherever the class is exposed in the user interface.

For example, put <code>ShowDetails</code> on <code>Person</code> when it acts on one <code>Person</code>. Do not make a separate copy of the action for each ViewModel that shows people.

{| class="wikitable"
! Action type
! Context available to the action
! Use it when
|-
| Class action
| The object instance of its owning class, available as <code>self</code>.
| The operation belongs to the model object and should be reusable across views.
|-
| [[Documentation:ViewModel actions|ViewModel action]]
| ViewModel state, including <code>vCurrent_</code> and <code>vSelected_</code> variables for relevant ViewModel nestings.
| The operation depends on what is focused, selected, or otherwise specific to one view.
|}

[[File:Class Actions - Image 2.png|frameless|342x342px]] 
== Context and expressions ==
A class action always has an instance of its owning class as its root context. In the action's Enable Expression and Execute Expression, <code>self</code> refers to that instance.

For example, when an action belongs to <code>SysSuperClass</code>, <code>self</code> has <code>SysSuperClass</code> as its context. Write expressions that navigate from <code>self</code> through the model associations and attributes needed by the action.

Class actions cannot use the ViewModel variables <code>vCurrent_</code> or <code>vSelected_</code>. Those variables describe a particular view and are available to [[Documentation:ViewModel actions|ViewModel actions]], not class actions.

The Enable Expression determines whether the action is enabled for the current object. The Execute Expression defines what happens when the action runs. These expressions use [[Documentation:Learn OCL|OCL]] and action behavior as configured in the action definition.
== Create a class action ==
In MDriven Designer, create the action from the class that owns the behavior.

# Open the model diagram containing the class.
# Right-click the class header.
# Select '''Add Class action'''.
# Enter an action name.
# Define the Enable Expression if the action should only be available in a particular object state.
# Define the Execute Expression or select the applicable standard action behavior in the action definition.
# Save the model.

You can also display a class's existing class actions by selecting the small arrow triangle at the top of the class in the diagram view. From that display, you can create actions and define drag actions.

[[File:Class Actions - Image 3.png|frameless|565x565px]]  
== Name actions for readable presentation ==
Name class actions in camel case. MDriven splits camel-cased names into words for presentation until you choose to change the presentation.

For example:

{| class="wikitable"
! Action name
! Initial displayed name
|-
| <code>ShowCustomerDetails</code>
| Show Customer Details
|-
| <code>CreateInvoice</code>
| Create Invoice
|}

Use names that describe what the user can do. For example, prefer <code>ShowCustomerDetails</code> over <code>DoIt</code>.

[[File:Class Actions - Image 4.png|frameless|238x238px]]  
== Availability in views ==
Class actions are globally available to views that show objects of the owning class, subject to the ViewModel's type context and action inclusion settings. This lets one action follow an object type through the application instead of being recreated for each view.

For example, when a ViewModel nesting is typed as <code>Person</code>, actions defined for <code>Person</code> can appear there. If that nesting is changed to <code>Car</code>, the <code>Person</code> actions no longer match that type context and actions for <code>Car</code> can appear instead.

You can control whether a matching class action is included at a ViewModel location:

* In the action definition, review the ViewModel places whose type information matches the action.
* Use the opt-in setting to control inclusion at those matching levels.
* In the ViewModel tree, use the arrow in front of a class action to opt it in or out at that location.

See [[Documentation:Turnkey session 3: Opting out actions|Opting out actions]] for the opt-in and opt-out workflow.
== Reuse actions from a related class ==
Sometimes a grid needs to show objects of class <code>B</code>, while the relevant actions belong to a related class <code>A</code>. Instead of duplicating the actions on <code>B</code>, configure '''Act As For Actions''' in the ViewModel nesting with an expression that navigates from <code>B</code> to zero or one <code>A</code> object.

For example, if <code>B</code> has an association to <code>A</code>, use <code>self.A</code> when that expression results in at most one <code>A</code>. The context remains <code>B</code>, but MDriven can expose the actions of <code>A</code>. See [[Documentation:Act as For Actions|Act As For Actions]] for the full pattern.
== Drag actions ==
A drag action is a class action that responds when one on-screen object is dragged onto another object. Define drag actions from the class-actions display for the relevant class. Use a drag action only when the interaction is based on the participating model objects; use a ViewModel action when it requires view-specific state.

[[File:Class Actions - Image 5.png|frameless|339x339px]]  
== Class actions in tables ==
Class actions can be placed in a table on a screen. Their enabled or disabled state works as it does elsewhere in the user interface. For the table-specific behavior and the limitation for ViewModel/context actions, see [[Documentation:Web client actions in tables|Web client actions in tables]].

[[File:Class actions Image 6.png|frameless|483x483px]]  
== See also ==
* [[Documentation:Actions]]
* [[Documentation:ViewModel actions]]
* [[Documentation:Act as For Actions]]
* [[Documentation:Turnkey session 3: Opting out actions]]
* [[Training:Bootcamp:Chapter 5]]

[[Category:Actions and Business Logic]]
[[Category:Actions overview (class and instance scope)]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]