Calling actions from views

You can invoke actions from views. The actions are called in the Application Engine.

Before you begin

Before you begin, the action should already be built.

About this task

To call an action from a view, you must specify configuration options of type Action in the view variable declarations and select a default action to be used. The default action is the application programming interface (API) for which custom actions must match. The names and types of both inputs and outputs must match.

Procedure

Open a view and then specify an Action type configuration option in the variable declarations.
1. In the Variables page, click the plus sign next to Configuration options.
2. Under Data, select the Service type option, select the default action, and then provide a name to represent this configuration option action.
  
  Note: The default action can optionally be overridden with a compatible action by users of this view.

Implement the action.

Call the action by using a simple JavaScript call syntax or a REST API.

In the Behavior page, under Event handlers, select a method (load, unload, view, change, or collaboration) and then provide code for calling the action. Use the following guidelines for your event handler code.

Calling the action using a JavaScript call syntax:

Use: this.context.options.<service_option_name>(args)

Table 1. Optional properties for `args` JavaScript object
Property	Description
params	(String or Object) A JSON string that represents the input to the action. If an object is provided, it will be serialized into JSON format using `JSON.stringify()`. As such, the object must be JSON serializable.
load	(function) A callback function when the action call returns successfully. The callback function has a single parameter that contains the output of the action call.
error	(function) A callback function when the action call results in error. The callback function has a single parameter that contains the error information.

Note: The action is called only using JSON input and output.

Calling the action using a REST API:
- Use: this.context.options.<service_option_name>.url (This contains the action URL.)
- Serialize your input data in JSON format and add it to the URL using params as the parameter name.
- Call the URL using an XHR call and specify the following properties appropriately: handleAs, headers, sync, load, error properties.

Restriction: If the action uses an error end event with error code and error data, the content of the modeled error in the action is not available in either the JavaScript error property or in the REST API error property. The error message returned contains the error code but no error data.

Click Save or Finish editing.

Example

The following example is JavaScript code for a load event handler:

var _this = this;
var input = {text: this.context.options.service_option_name.get("value")};
var serviceArgs = {
  params: JSON.stringify(input),
  load: function(data) {
console.log("service returned: ", data);  
    // now dynamically create the img tag
    require(["dojo/_base/url"], function(url) {
       var relPath = new url(data.path).path;
       domConstruct.create("img", {src:relPath, style:"margin:5px 0px"}, _this.context.element, "first");     
    });
  },
  error: function(e) {console.log("service call failed: ", e);}
} 
this.context.options.service_name(serviceArgs);

Tip: If the action output is a complex-type business object, the data object that you get from the response contains a property holding the metadata of your object, for example:

{"status":"200","data":{"serviceStatus":"end","key":"@54","step":"End","data":
{"bookPlacedPosition":{"Floor":1,"Room":"101","Row":2,"@metadata":
{"dirty":true,"shared":false,"rootVersionContextID":"2064.c30905ba-8d17-41f4-
b2a8-08cbb6516ff0T","className":"PlacedPosition"}}},"actions":null}}

If you directly set the response object to your binding like the following example, the @metadata object is added in your structure:

this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);

When you trigger the boundary event to the server, the server throws an exception because it does not expect the boundary event to have the @metadata object. To avoid an exception, remove the @metadata object from the response before you set it to the binding, for example:

delete data.bookPlacedPosition['@metadata'];
_this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);