Executing Actions¶
Assigning Actions In Metadata Definitions¶
Actions can be assigned as handler of an event in the metadata definitions. When the event is triggered, the assigned action will be executed.
-
You can assign them in the Events tab in the layout editor or in the Action editor. Pressing the 'link' icon beside the event input field will display a list of actions that you can choose from.
-
You can also assign action via code editor:
"OnPress": "/MyApp/Actions/NavigateToDetail.page"
Executing Actions in JavaScript Rule¶
Actions can also be executed in a JavaScript rule via the executeAction
function of the ClientAPI
class.
For example
return clientAPI.executeAction("/MyApp/Actions/NavigateToDetail.action");
clientAPI.executeAction
function will return a promise, the success and failure of the promise is equivalent to the OnSuccess
and OnFailure
.
let deletePromise = clientAPI.executeAction("/MyApp/Actions/DeleteProductEntity.action");
return deletePromise.then((result)=>{
return clientAPI.executeAction("/MyApp/Actions/NavigateToProductList.action");
}), (error)=>{
alert(`Action Failed: ${error}`);
}));
Actions Chaining¶
When an event (such as OnPress
or OnLoaded
) is triggered, it will execute its assigned event handler which can be an action or a JavaScript rule.
The triggered event's execution will last until all of the chained actions or rules are completed.
Chaining event handlers is done by using promise
chaining.
- You can chain an action with another action/rule by assigning another action/rule to the
OnSuccess
orOnFailure
orOnInvalid
event of that action. - You can chain a rule with another action by using
ClientAPI.executeAction
function and return itspromise
object from the rule. - You can chain a rule with another rule by importing the rule, call the rule function and return its
promise
object. - You can chain a rule with multiple actions or rules by combining them into a
Promise.all
and return the consolidatedpromise
object.
With this approach, you can chain as many actions/rules as needed.
Note
Action execution is an asynchronous operation. When you execute an action in a rule, it's not immediately executed. The executeAction
function will return a promise
object to let you wait.
If you execute an action in a rule and return from the rule, the app will check if you have returned a promise
object from the rule. If a promise
object is returned from the rule, then the app will wait for the promise
to be resolved before completing the execution of the rule and releasing the context resources such as action binding. If no promise
object is returned from the rule, the execution of the rule will be completed immediately and action binding will be released, and by the time your action is finally executed it will no longer have access to the action binding.
So it is important that you return the promise returned by the executeAction
function from the rule (chaining the action), if you want the action to be able to access the action binding.
Overriding Actions¶
Starting mobile development kit 4.3, you can override the properties of an action that you want to execute. This allows you to re-use an existing action for different purpose.
For example, you have created a Toast Message action named ShowToast.action
with message "Hello World" and duration of 5 seconds. Using the override feature, you can execute ShowToast.action
but replacing the message with different text "Hello Moon". When the action is executed it will show "Hello Moon" for 5 seconds.
Note
You can override a subset of an action's properties, existing properties that was not overridden will be kept and used as they are.
You can also set additional property that was not initially defined in the action itself.
Overriding an Action In Metadata Definitions¶
After assigning an action to an event, you will see a pen with angled arrow icon appear. Pressing the icon will show a dialog box with a list of properties that of the assigned action. You can set any of the properties and save it. When the event is triggered and the assigned action is executed, it will be executed with the overridden properties.
You can override it via code editor too:
Actions can be set as event handler with overridden properties in the metadata definition by assigning an object with Name
and Properties
.
For example, you have a SimpleMessage.action
that shows "This is a simple message"
and closes when user pressed the OK
button:
// /MyApp/Actions/SimpleMessage.action
{
"_Type": "Action.Type.Message",
"Message": "This is a simple message",
"OKCaption": "OK"
}
You can assign the action to an OnPress
event and override its properties:
//Excerpt of a page
{
"ObjectCell": {
"Title":"Press to show a message",
"OnPress": {
"Name": "/MyApp/Actions/SimpleMessage.action",
"Properties":{
"Message": "This is an overridden message",
"OnSuccess": "/MyApp/Actions/NavigateToAnotherPage.action"
}
}
}
}
When the Object Cell is pressed, it will show a message dialog with the text: "This is an overridden message"
and will navigate to another page when user pressed the OK
button.
Overriding an Action in JavaScript Rule¶
Actions can also be executed with overridden properties in JavaScript rule via the executeAction
function by passing an object with Name
and Properties
.
Name
is the path to the action you want to execute.Properties
is the collection of key value pair of the properties you want to override.
For example:
return clientAPI.executeAction({
"Name": "/MyApp/Actions/SimpleMessage.action",
"Properties":{
"Message": "This is an overridden message",
"OnSuccess": "/MyApp/Actions/NavigateToAnotherPage.action"
}
});
You can also do multiple actions overrides.
In the following example, we are overriding properties of DeleteProductEntity.action
and at the same time also override the ShowSuccessMessage.action
that will be executed in the OnSuccess
event of DeleteProductEntity.action
.
let newReadLink = getReadLinkFromSomewhere();
let deletePromise = clientAPI.executeAction( {
"Name": "/MyApp/Actions/DeleteProductEntity.action",
"Properties":{
"Target": {
"ReadLink": newReadLink
},
"OnSuccess": {
"Name": "/MyApp/Actions/ShowSuccessMessage.action"
"Properties":{
"Message": "You have successfully deleted the product"
}
}
}
});
return deletePromise;