Mapping

Working with service/ components mapping in Ionic 4/5 apps

When a service is to be invoked in an app, it usually requires inputting 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 need for further actions.

Working with Mapping Editor

To start defining input or output service mapping, go to the page DATA panel and make sure you have added at least one service component on the page. You’ll see a list of service events that can be used to add actions including Mapping:

👍

Service mapping is available only if it is used as an action for events of the datasource (Before send and/or Success) added in the DATA panel.

Use the Before send event to define input mapping and the Success event to define output mapping. Mapping actions for Before send and Success events are automatically created for each new datasource:

There are a number of events and actions that can be chosen for a certain service.

Input Mapping

Now, let's see how to create an input mapping from scratch:

  1. Click Add to the right of the Before send event field and choose Mapping.
  2. The mapping window will then appear. You can map the input by dragging and connecting elements on either side:

In the above screenshot, the value from the Form Data (as object) component is mapped to the $ service body request. To create such a connection, select Form Data (as object), and drag and drop it over the $ on the right. Once it’s over $, release the mouse button; this way the connection is created.

  1. Note that with mapping, we can also set the default values to be sent. For example, in this service, the X-Appery-Database-id is provided with the default {myDB_settings.database_id} value.

Click Save & Replace when finished, and you’ll see that the Mapping action has been saved for the Before send event on the EVENTS tab.

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 way to input mapping - by clicking and dragging an element to the other side:

Actions mapped to the Success event will only be invoked in the case of the REST service Success event.

Deleting Mapping

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

Components Mapping

In Ionic 4/5 projects, you can also create mappings to and from component properties.
First, open the DESIGN panel, unfold the EVENTS tab from the bottom, then select the needed component (here, Button) and select the Mapping action to define the button behavior:

The new window with the Mapping editor opens. Now, you can define mappings for the Button Click event:

📘

Please check this page to learn how to bind UI components in an Ionic 4/5 app.

Storage and Variable Mapping

Mapping storage and/or variables is available only when variables (storages) have a custom model type that has arrays in its structure.
Such a custom model can be specified on the Model and Storage tab of Project settings. You can check here for more information.

📘

Want to know more?

You can also apply mapping to the Selected property of its options. Please read here to learn more.

Error Handling

If the service returns an error, the Error event can be used to invoke a custom JavaScript and notify the user of the error.

🚧

The Mapping action is not available for the Error event.

When these events are used, you can choose to apply the actions from the Add dropdown list:

To add an event:

  1. Make sure you are in the DATA panel.
  2. Click Add to the right of the Error event.
  3. From the dropdown list, select Present toast:
  1. Provide details to handle the event behavior:
  1. Click Save. Once this is done a new action will be added to the right of the Error datasource event and will be listed in the EVENTS tab among the other page events: