View source for Documentation:ListActions

You can use '''ListActions''' in a [[Documentation:SelfVM|ViewModel]] expression to retrieve the actions available for a specified nesting and use their metadata when you customize how actions appear in the user interface.
== Use ListActions ==
<code>ListActions</code> is an [[Documentation:Learn OCL|OCL]] operator on <code>selfVM</code>. It returns the available actions for a [[Documentation:Nestings|nesting]] as a collection of <code>ActionInstance</code> values.

Use the nesting reference rather than a hard-coded nesting name when possible. Passing <code>selfVM.Nesting</code> gives better error checking if the nesting name changes.

<syntaxhighlight lang="text">
selfVM.ListActions(selfVM.Nesting)
</syntaxhighlight>

For example, if the current ViewModel context is the nesting whose actions you want to display, this expression gives you the collection of action instances that are available in that context.

The syntax for ListActions is:
<syntaxhighlight>
selfVM.ListActions(<nameofNesting>)
</syntaxhighlight>
== Arguments and return value ==

{| class="wikitable"
! Item
! Type
! Description
|-
| <code>nameofNesting</code>
| String
| The name of the ViewModel nesting whose available actions you want to list. Use <code>selfVM.Nesting</code> instead of a literal name when it represents the intended nesting.
|-
| Return value
| <code>Collection(ActionInstance)</code>
| A collection containing the action instances available for that nesting.
|}
== Read action metadata ==

Each returned <code>ActionInstance</code> describes an action and the information needed to present it. For example, you can use <code>Enabled</code> to identify actions that can currently run, <code>Hint</code> for hover information, and <code>Group</code> to organize actions in menus.

{| class="wikitable"
! Attribute
! Type
! Meaning
|-
| <code>ActionName</code>
| String
| The name of the action.
|-
| <code>Enabled</code>
| Boolean
| <code>true</code> when the action is enabled.
|-
| <code>Group</code>
| String
| The name of the action's menu group.
|-
| <code>Hint</code>
| String
| Extra information shown when the pointer is over the action UI widget. A hint is available for both enabled and disabled actions.
|-
| <code>IsNavigating</code>
| Boolean
| <code>true</code> when the action navigates to another ViewModel.
|-
| <code>NestingName</code>
| String
| The name of the ViewModel nesting for the action.
|-
| <code>Presentation</code>
| String
| The string representation of the ViewModel.
|}
== When to use it ==

Use <code>ListActions</code> when you build or customize an action display and need to discover the actions available in a particular nesting. It lets the UI use the action definition's name, group, hint, enabled state, and navigation behavior rather than duplicating that information.

For example, an action menu can obtain the available action instances for a nesting, place actions with the same <code>Group</code> together, display <code>Hint</code> as hover text, and retain disabled actions so that their hints remain available.

<code>ListActions</code> lists available actions; it does not execute them. Before running a known action from OCL, use [[Documentation:OCLOperators CanExecuteAction|CanExecuteAction]] to check whether it can run, then use the appropriate action-execution mechanism. See [[Documentation:Actions]] for action types and behavior.
== See also ==

* [[Documentation:SelfVM]]
* [[Documentation:Nestings]]
* [[Documentation:Actions]]
* [[Documentation:OCLOperators CanExecuteAction]]
* [[Documentation:Web client actions in tables]]

[[Category:Actions and Business Logic]]
[[Category:Actions overview (class and instance scope)]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]
[[Category:ViewModel nestings and parameters]]
[[Category:ViewModels and UI Modeling]]