Action and ActionGroup

An Action in ADITO is a model that executes JDito code. In addition to predefined Actions such as save, new, cancel, or delete, you can define custom Actions for project-specific requirements.

An ActionGroup is used to group Actions for specific ViewTemplates, for example Table. These ViewTemplates provide dedicated properties for referencing ActionGroups, usually named favoriteActionGroup1, favoriteActionGroup2, and favoriteActionGroup3.

To assign an Action to an ActionGroup, create and configure the Action first and then drag it onto the ActionGroup in the Navigator. The Action is then shown as a child element of the ActionGroup. You can assign any number of Actions to one ActionGroup.

Configuration

Actions belong to an Entity because they are always executed in the context of that Entity.

To create an Action, open an Entity in the Navigator and choose New Action from the Entity context menu. Enter a camelCase name (see ADITO Information Document AID001) and confirm. The new Action appears under the Actions node. The most relevant properties are:

• title: Text shown in the Actions menu or as the button label.
• tooltip: Tooltip text shown for the Action button.
• stateProcess: Logic that controls the Action state, for example whether it is disabled. By default, Actions are enabled.
• onActionProcess: The JDito code that is executed when the user triggers the Action.
• isMenuAction: See Appearance.
• isObjectAction: See Appearance.

Appearance

In ADITO xRM, Actions usually appear in the following places:

• In the PreviewView
  • Via the three-dot button. This button is part of some ViewTemplates, especially Card, and usually also contains the default Delete Action.
  • As separate Action buttons via properties such as favoriteActionX
• In the FilterView, above some ViewTemplates such as Table via properties such as favoriteActionGroupX. In this area, Actions can appear
  • as separate buttons,
  • grouped in ActionGroups, or
  • inside the three-dot menu.

Whether and where an Action appears depends on the following properties:

• isMenuAction: Defines whether the Action is shown in the client at all. If this property is false, the Action is not shown anywhere, regardless of the other settings.
• isObjectAction: Defines whether the Action is shown in relation to one specific dataset, for example in the PreviewView three-dot menu.
• selectionType: See the property description in the Properties view.

In a FilterView, an Action is only shown if it belongs to an ActionGroup and that ActionGroup is referenced in a favoriteActionGroup property of the corresponding ViewTemplate, for example Table. This is independent of the selectionType setting.

isMenuAction	isObjectAction	selectionType	Visibility
false	false	UNBOUND	nowhere
true	false	UNBOUND	as button via FilterView (only when specified via favoriteActionGroup)
false	true	UNBOUND	nowhere (isMenuAction = false)
false	false	MULTI	nowhere (isMenuAction = false)
true	true	UNBOUND	PreviewView (via three-dotted button), as button via FilterView (only when specified via favoriteActionGroup)
true	false	MULTI	as button via FilterView (only active, if at least 1 dataset is selected)
false	true	MULTI	nowhere (isMenuAction = false)
true	true	MULTI	PreviewView (via three-dotted button), as button via FilterView (only active, if at least 1 dataset is selected & if specified via favoriteActionGroup)

Figure: Visibility of Action buttons depending on property settings.

Multi Selection Action

For an example of a multi-selection Action, inspect ChangeParticipantStatus_action of EventParticipant_entity in module event.

This implementation uses an additional context named EventParticipantsChangeStatus. That context contains its own View for user input. Its Entity uses a datalessRecordContainer, contains one field that is linked to the keyword Entity through a Consumer in order to load participant states, and provides an Action that contains the update logic. The Action in EventParticipant reads the current selection as a recipe and forwards it through a Parameter into the additional context. The Action of EventParticipantsChangeStatus then reads the recipe, resolves the selected record IDs, writes the new status via SqlBuilder, and finally closes the current image.

Handling invalid selections

When you configure an Action that requires one or multiple selected datasets (selectionType = MULTI), you must decide how to handle invalid selections, meaning datasets for which the Action is not possible, not allowed, or not meaningful.

There are at least 3 options:

1. Ignore invalid datasets and process only the valid ones. This is the most common approach in practice.
2. Disable the Action button when at least one invalid dataset is selected by using stateProcess. The drawback is that the user does not automatically receive feedback about the reason.
3. Show an error message and abort the Action without making any changes.

The customizing training course contains code examples for all three approaches in Return selected cars.

All approaches are valid. The best choice depends on the project requirements and the expected user experience.