Mapping

When a REST service is invoked, it usually requires input data. In most mobile apps, the data comes from the page (user-entered) or from storage (previously saved). When the service is invoked, it returns the data you want for further actions with it. To start input or output mapping, go to Data view, and make sure you have at least one service component on the page. You’ll see a list of service events that can be used to add some actions:

Use a Before send event to define input mapping, and one of three events – Success, Error or Complete, to define output mapping.

Input mapping

There are number of events and actions that can be chosen for a certain event. Mapping actions for Before send and Success events are automatically created for each datasource.

To configure that mapping, simply click on an appropriate action:

But lets see how to create an input mapping from scratch: Click Add to the right of the Before send event field, and choose Mapping:

The mapping window will appear. You can map the input by dragging and connecting elements on either side:

In the above screenshot, the value from the Input component text_input is mapped to services input_param parameter. To create the connection, click Text, and drag and drop it over input_param. Once it’s over input_param, release the mouse button; this way the connection is created. It’s also possible to do it the other direction; by first clicking on text_input and then connecting to Text.

You can show or hide certain items by selecting needed checkboxes. For example, check “Storage” to show defined storage variables for further mapping:

Read more about storage types and API.

Click Save when you’ve finished, and you’ll see that the Mapping action has been saved for the Before send event.

Output mapping

Output mapping takes data returned from the service and maps it to the page or to the storage variables.  Click Add to the right of the Success event, and select Mapping:

Output mapping is done in a similar fashion to input mapping; by clicking and dragging an element to the other side:

Actions mapped to the Success event will be invoked only in the case of the REST service Success event. To invoke mapping actions in both cases (Error or Success), use a Complete event. Or use an Error event to make certain mappings only in the case of error.

Read more about Error and Complete events in Error handling section.

Deleting a mapping

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

Collections

It’s common to get back a list of items that are then displayed on the page. To display the data from a collection, map the top array element ($[i]) from the service to one of the following components, and you get an automatic “looping” feature. When you create the response automatically, the array element has a checked box in the “Array” column:

Grid

The following is an example of mapping to a Grid component. Notice the connection from $[i] to the Grid component. This is required to display all records in the collection:

List

The following is an example using the List component. Note that you are mapping to the mobilelistitem, not the list:

If you place other components inside the list, the mapping should look like:

Collapsible block

The Collapsible block component:

Radio button

Mapping to the Radio button. Note that a Radio button group is created:

Checkbox

Mapping to the Checkbox:

Select (Select menu)

Mapping to the Select menu:

Invoking JavaScript

You needed to frequently modify data for services request or for a services response. For example, you could want to wrap user entered data with certain JSON, so that the service will understand the request correctly, or you could validate and modify response data by removing unnecessary items from the service response. It can easily be done by invoking a custom JavaScript code that will process the data before actually mapping.

1. For Before send mapping, the custom JavaScript is invoked before the value is mapped to the request parameter.
2. For Success/Error, the custom JavaScript is invoked before the value is mapped to the screen UI.

Let’s say that any value entered by the user has to be sent to the service in upper case. Click JS left to the needed parameter (input_param in this case):

A JavaScript editor will open where you can then enter the JavaScript code. When mapping from an UI to request Before send mapping you will be provided with value parameter, which is your passed data. Your code must end with a return statement:

Invoking JavaScript is also possible when mapping from a service response (Success\Error events). In this case, in addition to the value argument an element argument is passed as well. An Element is the jQueyMobile element to which the mapping is done.

Editing response before mapping

Instead of editing your response data during actual mapping, you could launch a dedicated JavaScript function to do it for you. It is useful when you need to rewrite the response data with filtered/edited values instead of doing this each time for each mapping. For example, you could remove any unnecessary values.

Lets say, your service response has an unneeded first value and you want to remove it from the response:

1. Add a new Run JavaScript action for a Success event of your datasource.
2. By using drag and drop move this action to very beginning so the Mapping action will be able to the Run JavaScript. This way it’s guaranteed that the JavaScript code will be executed before the mapping.
3. Click on Run JavaScript action and write your code. You have a data parameter in this JavaScript function – this is your response value.
4. Write your custom logic to modify the response data. For example, to remove the first item of the response array (works only for arrays, not for JSON objects) use the following code:
   
   1	data.splice(0, 1);

Combining requests from several components

There can often be situations where this request must be combined with several values from different components. For example, there are two Input components (student_name and student_id) where the user can type studentName and studentId. You should add a where parameter to your REST service request, then click JS to the left of the where parameter to open up the code editor:

Add the following JavaScript code:

Click Save & Return. The formed query will look like:

Read more about $or and $and operators via the link.

In this case, there are no mapping arrows:

Mapping a JSON array

To map a JSON array, click JS near the needed parameter and specify the JavaScript code in the following form:

Updating existing apps

There used to be Request and Response mapping in the builder.

The Request mapping is now interpreted as Before send and the Response mapping is interpreted as Success:

On this basis, you shouldn’t do anything to transfer your mapping logic. Everything will be done automatically.

Error handling

The REST service instance supports the following events when invoked:

1. Before send – this event is always called before the REST service invocation. In scope of error handling it can be used with custom JavaScript to validate the Request parameters.
2. Complete – this event is always called at the end, regardless of whether the request was successful or an error occurred.
3. Error – this event is only called if an error occurred with the request.
4. Success – this event is called only if the request was successful; no errors from the service or errors in the data were returned.

Error and Success events cannot ever both be called in the same request.

A number of actions can be defined when an event is fired. For example, if the service returns an error, the Error event can be used to invoke custom JavaScript and notify the user of the error. Mapping actions are also available for all datasource events (including Error and Complete).

When these events are used, you can use the function arguments in the Run JavaScript action. To add an event:

1. Make sure you are in DATA view.

2. Click Add to the right of the Error event.

3. From the drop-down list, select Run JavaScript:

4. Provide JavaScript code to handle the error:

5. Click Save. Once it’s done, the new action will be added to the right of the Error datasource event:

Check for empty service response

There are no universal ways to check the service response emptiness, because it depends on the response structure. However, here is a common working variant: