If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

Overview

When a REST service is invoked, it usually requires input data and returns the response data you want for further actions with it.

With Appery.io Visual Editor, it’s very fast and simple to map data between the scope and REST API services. This works either on request and on response. Arrow is showing the mapping direction.

The custom case of mapping is Binding. It ties UI to Scope with double directed arrows.

Introduction

Mapping allows you to connect scope variables to service request/response parameters.

For example, you have a service with the following response parameters of types Boolean and String:response

Create scope variables of the appropriate types:
scope

Now you are ready to create a mapping between response data and scope variables.

Opening Mapping editor

To open Mapping editor do the following steps:

  1. Create a new service with needed parameters and open any screen.
  2. To start input or output mapping, go to SCOPE view and create any function (by clicking Add) or open an existing one (by clicking Edit).
  3. In the function editor, click the arrow to filter snippets, select Invoke service, and click Insert snippet. Then, click <Backspace> to delete a default name with quotes. Then enter a service name manually or click <Ctrl>+<Space> to autocomplete.
  4. The Mapping buttons for request and response parameters are automatically created when you select the Invoke service snippet. They can be used to add some actions – one before running a service to define input mapping and on the service Success event to define output mapping:
  5. Click an appropriate Mapping button (for request or response parameters) to configure that mapping.

Using Drag&Drop

Instead of invoking services in the code editor with subsequent auto completing, you can use a drag and drop feature to map new functions.

To do it, go to the SCOPE tab, locate the necessary service, and drag the service to the code editor. You can see the cursor position where the code will be inserted:

There are some issues to consider:

  • This feature doesn’t work for the Settings service.
  • This feature doesn’t work if the SCOPE tab is inactive.
  • You can drag any service (except Settings), but drop it to an allowed location only.

Mapping service parameters

When you click on the Mapping button in code the mapping window opens. To map the data, drag and drop elements to other side:
mapping_response

On the above screenshot, the value from the scope variable flag is mapped to services param1 parameter and the value from the scope variable text is mapped to services param2 parameter. To create the connection, drag and drop scope variable over service parameter; this way the connection is created. It’s also possible to do it in the other direction; drag and drop param1 to flag and param2 to text.

Mapping arrays

For example, you have a service with the following parameters:
service_response

Then, you would need to create an appropriate array model in Project > Model before mapping it to service parameters:
model

The final mapping will look like this:
mapping_service

Customizing

There are cases where straight mapping might not be enough. JavaScript code allows you to customize the mapping as needed:
customizing

You can see that the JS icon is blue on the above screenshot. That means there is JavaScript code behind it. Clicking on the icon, opens up an editor where you can write any mapping logic using JavaScript. Being able to write custom JavaScript allows you quickly to customize the app as much as you need.

For example, this code returns the result in large letters:

Deleting a mapping arrow

To delete a connection, select the line. A red cross icon appears. Click the icon to delete this connection:
deleting

If you use any custom JS code for this connection, you will see a confirm dialog with the JavaScript code to be removed. Click Delete to remove arrow and code. Click Cancel to do nothing. After removing arrows your code will be lost.

Saving mapping

Mapping screen has 3 buttons: Cancel, Save & Replace, Save & Show code:
image 003

  1. When you click Cancel, mapping changes won’t be saved and mapping code won’t be changed.
  2. When you click Save & Replace, mapping changes will be saved and previous mapping code will be replaced with new one.
  3. When you click Save & Show code, mapping changes will be saved and pop-up with new mapping code will be shown. If there is an error in code and the editor cannot find a needed self-executing function, the code and warning will be displayed. You would need to copy the code and paste it manually. The pop-up has 2 buttons: Close, Replace. Click Replace to replace previous mapping code with new one. If you click Close mapping arrows will be saved but this won’t affect the code itself. So, please use Save & Show code option only for advanced work with mapping.

When you’ve finished and saved changes, the mapping code will be inserted inside corresponding self-executing function.

You can open your saved mapping again to make any changes. You can also edit existing mapping code and replace it with new code. Please note it won’t make any changes to mapping editor so all the arrows won’t be changed.

If you have changed generated mapping function code and then edit mapping via mapping editor you will lose all the custom changes and the code will be replaced with new one.

If you need to change some part of custom mapping code, use Save & Show code instead of Save & Replace to copy the needed part of code and paste it where needed in order not to lose your custom changes.

Deleting Mapping button or changing service name in code leads to losing mapping. Be careful when renaming services. A service name in code must match the actual name of service instance.

Handling events

The REST service instance supports the following events:

  1. Before the REST service invocation, there is a Mapping button to edit mapping that generates request data from scope variables.
  2. Success – this function is called only if the request was successful; no errors from the service or errors in the data were returned.
  3. Error – this function is only called if an error occurred with the request.
  4. Notify – this function is called to send back a notification of progress. It provides updates on the status of the promise execution, and may be called multiple times before the promise is either resolved or rejected.

All the needed actions can be defined in a function code when an appropriate service event is fired. For example, if the service returns an error, the Error function can be used to invoke custom JavaScript to handle the service error.