Action and ActionGroup
An Action in ADITO is an option to execute arbitrary JDito code. Besides the predefined Actions (save, new, cancel, delete, etc.), you can specify further Actions according to your requirements.
An ActionGroup is an ADITO model to group Actions for being used in specific ViewTemplates, e.g., "Table". These ViewTemplates have special properties for referencing ActionGroups, usually named favoriteActionGroup1, favoriteActionGroup2, and favoriteActionGroup3.
To assign an Action to an ActionGroup, simply create and configure the Action (see below) and then drag and drop it on the ActionGroup, in the "Navigator" window. The Action will then appear subordinated to the ActionGroup. You can assign an arbitrary number of Actions to an ActionGroup.
Configuration
Actions are part of an Entity, because they are always executed in an Entity's Context.
To create and assign an Action, open an Entity in the Navigator window and choose option "New Action" in the Entity's context menu. Then, enter a name in camelCase (see ADITO Information Document AID001) and confirm with OK. The Action's name will appear under a new node named "Actions". Click on the new Action and look at its properties:
title: The text to be shown in the Actions menu (see below) or as Action button label.tooltip: The text to be shown as tooltip of the Action button.stateProcess: Code to specify cases when the Action should be in a specific state, e.g., disabled. By default, all Actions are available.onActionProcess: The actual code that will be executed when the user selects the Action.isMenuAction: see sub-chapter "Appearance"isObjectAction: see sub-chapter "Appearance"
Appearance
In ADITO xRM, Actions are usually shown in the following locations:
- In the PreviewView
- Selectable via the three-dotted button in the PreviewView. This button is part of some ViewTemplates (in particular, the "Card"-type ViewTemplate) and usually includes the default Action "Delete".
- As separate Action buttons (see properties "favoriteActionX" of some ViewTemplates, particularly "Card")
- In the FilterView, on the top of some ViewTemplates, e.g., "Table" (´see properties "favoriteActionGroupX"). Here, Actions can appear
- as separate Action buttons;
- clustered in ActionGroups;
- included in the three-dotted button.
Where and when an Action appears, depends on the settings of the following properties:
isMenuAction: defines if the Action is generally to be shown in the client. If this property is set to false, then the Action will appear nowhere in the client, whatever the other settings may be.isObjectAction: defines if the Action is to be displayed in relation to one specific dataset (selectable via the three-dotted button in the PreviewView)selectionType: see property description (bottom of property window)
In a FilterView, an Action is only shown, if it is part of an ActionGroup, and if this ActionGroup is specified as favoriteActionGroup in the property settings of the respective ViewTemplate (e.g., "Table"). This is independent from the state of property "selectionType".
| 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) |
Visibility of Action buttons according to property settings
Multi Selection Action
To see an example of how a multi selection action can be implemented, take a look at the ChangeParticipantStatus_action Action of the EventParticipant_entity of the ADITO xRM project.
In this example, an additional context is used, EventParticipantsChangeStatus. It has it own View, which serves as input. Its Entity uses a datalessRecordcontainer, contains one field, which is linked via a Consumer to the keyword Entity to get the participant states. It also contains an Action, which will
contain the change logic. The Action found in EventParticipant reads the current selection as recipe and puts in forward via a Parameter into the additional Context. The Action of the EventParticipantsChangeStatus uses the recipe to get all ids of the selected records and writes the new status via the SqlBuilder. At the end of the Action, the current image (the View of
EventParticipantsChangeStatus) is closed.
Handling invalid selections
When you configure an Action that requires the selection of one or multiple datasets (selectionType = MULTI), you are confronted with the question of how to handle invalid datasets, i.e., datasets for which the execution of the Action is not possible, not allowed, or makes no sense.
There are at least 3 options:
- In practice, the most common solution is to simply ignore all invalid datasets when the Action is executed.
- Alternatively, you could disable the Action button, if at least one invalid dataset is selected (using property
stateProcess). The disadvantage of this solution is that the user does not get feedback on the reason why the button is disabled. - A further option is to show an error message and abort the Action without any changes.
In the customizing training course, you can find code examples of these 3 options in chapter Return selected cars.
All options are possible. Which option you will implement depends on your project's requirements or on your customer's preferences, respectively.