Using a REST service on a page

Adding a service to a page

Once a service has been defined, it can be added and mapped to one or more pages. To add a service to a page:

Switch to Data view of the designer by clicking the Data tab:
For Add datasource, select Service and then the service you created:
Click Add button. A service instance will be added to the page:

By default the service instance has a name of ‘restserviceX’. You can change it to a more meaningful name by setting its Name property.

Mapping service input and output to the page

When a service is invoked, it usually requires input data. In most mobile apps, the data comes from the page (user entered). When the service is invoked, it returns data that we want to display on the page.

To start input or output mapping, go to Data view, make sure you have at least one service component on this page and then click Edit Mapping button:

Input mapping

Input mapping is taking value from the page and mapping it to service input parameters. Mapping is done by dragging and connecting elements on either side.

In the above screen shot, the value from input component searchInput will be mapped to services q input parameter.

To create the actual connection click either searchInput or Text and drag and drop it over q. Once over q, release the mouse button and the connection will be created. It’s also possible to do it the other way. First clicking on q and then connecting to searchInput or Text.

Output mapping

Output mapping is taking data returned from the service and mapping it to the page. Output mapping is done in a similar fashion to input mapping, by clicking and dragging an element to the other side.

Mapping Collections

It’s common to get back a list of items which is then displayed on the page. In order to display the data from a collection, map the top array element from service to one of the following components and you will get an automatic “looping” feature.

When you create the response automatically, the array element will have a check box in the array column. You will also be be able to expand it:

Grid

Here is an example mapping to a Grid component:

List

Here is an example using the List component:

Note that you are mapping to mobilelistitem, not the actual list.

Collapsible Block

Here is an example using the Collapsible Block component:

Radio button

An example of mapping to radio button. Note that a radio button group will be created:

Check box

Here is an example of mapping to check box:

Select (Select menu)

Select is another component can be used when mapping to a collection.

Mapping to/from Local Storage

If you need to reuse some values from a service on a different page, you can save the values in browser’s Local Storage. It’s also possible to use Local Storage as input for the service. The Local Storage is just the standard HTML5 Local Storage. Local Storage variables will be available on any app page.

To create a new local storage variable during mapping, enter a variable name and click Create > Local storage variable:

The variable will be listed under Local storage variables section:

To create mapping, connect the local storage variable to service input:

You can as easily save data from a service into local storage:

It’s important to point out that under the hood standard Local Storage API is used to save or get the values:

localStorage.getItem('name');
localStorage.setItem('name', 'value');

You can also use this API directly anywhere you can write custom JavaScript.

Mapping JavaScript

When doing input or output mapping, you always have a chance to write custom JavaScript before the mapping is done.

For input mapping, the custom JavaScript will be invoked before the value is mapped to the request parameter
For output mapping, the custom JavaScript will be invoked before the value is mapped to the screen UI

Let’s say any value that is entered by the user, has to be sent to the service in upper case. Click the green Add JS button:

A JavaScript editor will open where you can enter any JavaScript code. Your code must end with a return-statement — which is the value that will be sent to the service:

value - is the actual value entered by the user.

When doing output mapping, in addition to value argument, an element argument is passed as well. element is the actual jQuey Mobile element to which the mapping is done

function(value, element) {
   // your code;
   return some_value;
}

Setting default values during mapping

You are not required to map every service input parameter to an element on the page. It’s possible to set a default value for an input parameter. Simply enter any value as shown below:

You can also use JavaScript to provide a default value. Click the Add JS button and provide a default value. For example:

return "12345";

If you set default values during service creation:

then those values will be copied to service instance mapping:

Returning a JSON array (complex object) in JavaScript mapping

var jsonback = {
  "__type": "GeoPoint",
  "latitude": 10.0,
  "longitude": 20.0,
}; 
return jsonback;

Deleting a mapping (connection)

To delete a connection, select the actual line. A black icon will appear. Click on the icon to delete this connection.

Service events and error handling

The REST service instance supports the following events when invoked:

Complete - this event is always called at the end, regardless whether the request was successful or an error occurred.
Error - this event is only called if an error occurred with the request
Success - this event is called only if the request was successful. No errors from the service or errors in the data returned.

Note: both Error and Success events will never 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, Error event can be used to invoke a custom JavaScript and notify the user of the error. Learn more about using Events and Actions.

Under the hood, these events are invoked via these jQuery functions and their arguments which you may use:

onComplete': function(jqXHR, textStatus) {}
onSuccess': function(data) {}
onError': function(jqXHR, textStatus, errorThrown) {}

When these events are used, you can use the function arguments in Run JavaScript action.

To add an event:

Make sure you are in Data view
Open Events view
From Component, select the service instance
From Event, select the event you want to use
From Action, select Run JavaScript:

Service invocation order

By default, services are invoked in asynchronous order. Let’s say there is service A and service B. Let’s say both are invoked in order on button click:
On button click (invocation order):

Service A
Service B

There is no guarantee that service A will finish before service B is invoked. Basically, service A will be invoked and the execution will move to service B. If you need to ensure that service B is only invoke after service A is finished, then use service A success event to invoke service B.

Invoking a service from JavaScript

To invoke any service directly from JavaScript, use this:

serviceInstanceName.execute({});

serviceInstanceName is the name of the service instance from Data view.

Passing service data between pages

You have 2 pages. You would like to invoke a service on button click on page #1, navigate to another page and display the result from the service on page #2.

Here is how this can be done:

Invoke service on button click (on page #1)
Save data from service into Local Storage (on page #1)
Navigate to page #2 after the service has successfully finished. The navigation should happen on service’s success event
Read data from Local Storage to display on page #2

Saving JSON response from a service to local storage

Define a Success event for the service with this JavaScript:

var response = JSON.stringify(data));
localStorage.setItem("json_response", response);

If you look in Service events and error handling section, you will see what data is available to callback methods.

You can also just view the response in a console by running:

console.log(data);