Skip to content

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 or OnFailure or OnInvalid event of that action.
  • You can chain a rule with another action by using ClientAPI.executeAction function and return its promise 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 consolidated promise 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;

Last update: July 21, 2020