No UI is void of actions.
There are some simple actions but more complex actions require various steps to execute. Complex actions we call processes and will be the focus of other sections. In this section we will be looking at simple actions.
There are three types of actions.
- Local Context Actions – These are specific actions predefined for each screen context, such as on create screens, edit screens, or dashboards. The actions vary based on the particular context in which they are used.
- Local System Actions – These are universally available, hardcoded actions within the system. They function similarly to utility functions that are integrated directly into the client’s framework.
- Remote Actions – Actions that are executed on the server, pertaining to a particular entity. These actions are triggered based on the specified action and its parameters and are processed server-side.
Edit screen context actions
- context.close – Closes the currently open edit screen window.
- context.save – Commits and saves any modifications made on the edit screen.
- context.saveAndClose – First saves the changes made on the edit screen, then closes it, provided the save was successful.
- context.delete – Attempts to remove the current record.
- context.undo – Reverts any changes that have been made on the edit screen.
Create screen context actions
This context has all the same actions as the edit screen context but in addition:
- context.saveAndNew – Save the current captured data and if successful create a new record.
Dashboard context actions
- context.navigateToDetails – navigate to the master detail screen with the current selected records.
Defining actions
Actions are defined on the root of the schema on a “actions” property.
{
"actions": [
{
"id": "close_screen",
"action": "context.close"
},
{
"id": "save_changes",
"action": "context.save"
},
{
"id": "save_and_close",
"action": "context.saveAndClose"
},
{
"id": "save_and_new",
"action": "context.saveAndNew"
},
{
"id": "delete",
"action": "context.delete"
},
{
"id": "undo",
"action": "context.undo"
}
],
"body": { ... }
}When you have an action button, you can execute one of the predefined actions by clicking on it. This functionality is enabled by configuring the ‘action’ property in the button’s definition.
{
"element": "action-button",
"id": "btnCancel",
"styles": "aux",
"title": "@translations.AMPC.actionbutton_cancel",
"action": "undo"
}Remote actions
Remote actions are set up similarly to context actions, but they include specific remote details necessary for executing the action on the server.
{
"actions": [
{
"id": "action_id",
"remote": "Person",
"action": "PromotePerson",
"parameters": {
"id": "@ui.selectedPerson",
"status": "admin"
}
}
],
"body": { ... }
}The parameters here are the same as in a remote data source or data set primary actions.
- remote – Specifies the entity on which the function will be executed.
- action – Defines the specific action to be executed on the entity.
- parameters – A dictionary of the necessary parameters for the remote action.
System actions
- setVariable – Set a value to a schema variable at a specified path with an optional “condition” property. If a condition is provided and it evaluates as true, the specified variable is set. The “name” property indicates the path of the variable, and the “value” property defines the value to be assigned. Exclude the condition property if conditional actions are not required.
- setValueFromExp – Sets a value in a context object using a binding expression. This action includes an optional condition; the value is set only if the condition is met. Omit the condition if it’s unnecessary. The “values” property is a dictionary, where each key represents the path to set the value, and the corresponding value is a binding expression used to construct the final value.
- setValidation – Implements validation criteria for a field in the dataset. Available validation rules include:
- readonly: The field cannot be modified.
- required: The field must not be empty or null.
- min: Specifies the minimum numeric value allowed.
- max: Specifies the maximum numeric value allowed.
- minlength: Sets the minimum character length for a string value.
- maxlength: Sets the maximum character length for a string value.
- pattern: Requires the value to match a specified regular expression pattern.
- postMessage – Sends an event aggregation message to a component, as detailed in the binding engine documentation.
- emit – Triggers an event aggregation message, with further details available in the binding engine documentation.
{
"actions": [
{
"action": "setVariable",
"condition": "model.person.age > 60",
"parameters": {
"name": "ui.description",
"value": "Too young to handle"
}
},
{
"action": "setValueFromExp",
"condition": "model.person.age > 60",
"values": {
"model.fullName": "${model.firstName} ${model.lageName}",
}
},
{
"action": "setValidation",
"parameters": {
"model.position": "readonly"
}
},
{
"action": "postMessage",
"parameters": {
"query": "#person-component",
"action": "update",
"parameters": {
"id": "model.selectedId"
}
}
},
{
"action": "emit",
"parameters": {
"key": "confirm",
"message": {
"includeChildren": true
}
}
}
],
"body": { ... }
}Triggering actions
Besides clicking on a button there are also other ways to trigger actions.
- Custom Action Triggers – These initiate a sequence of actions whenever a monitored property undergoes a change.
- Custom Action Events – These involve defining a condition and monitoring for changes in properties related to that condition. When changes occur, the condition is assessed, and if it is met, a sequence of actions is executed.
customActionTriggers
Define custom action triggers on the root of the schema on a property called “customActionTriggers”. This is an array as you can define a number of different triggers. Triggers have two required properties.
- trigger – Refers to the path of the property whose changes are being monitored.
- actions – A list of actions, as previously defined, to be executed in response to the trigger.
{
"customActionTriggers": [
{
"trigger": "model.person",
"actions": [
...
]
}
],
"body": { ... }
}customActionEvents
This functions similarly to custom action triggers, with one key distinction: rather than defining a specific trigger, it specifies a boolean expression. When this expression evaluates to true, the defined actions are executed.
{
"customActionTriggers": [
{
"event": "model.person.age > 60",
"actions": [
...
]
}
],
"body": { ... }
}