Native Contacts Integration

Modeling Actions with WebRatio Platform
159 views Published on May 12, 2015 | Time 7 min
Applies to: 8.0 or higher

mobile applications usually interacts with the device in several ways. This lesson shows you how you can model with WebRatio Mobile Platform a Mobile Application that interacts with the device address book. You will learn how to specify the saving of a contact in the device address book and also the pick of an existing contact from the address book.

Transcript

Table of contents

Lesson Overview

The interaction between a mobile application and a device is sometimes useful for certain functions. This lesson shows you how to integrate your mobile application with the device address book. The integration with the address book works in two different modes: save a contact and pick a contact. This lesson shows you how to integrate your mobile application with the device contacts app using WebRatio Mobile Platform.

Save Contact

Let's suppose we want to create a mobile app showing a list of employees. The user can select an employee from this list and add it to his device contacts.

Let's start by creating a new Mobile Project. In WebRatio Platform, click "File", then "New" and finally "Mobile Project". In the opening dialog write a name for the project, then press the "Finish" button.

Once we have the Mobile Project, we need to define the "Employee" class in the Domain Model. Select the class element from the toolbar and place it in the work area. Let's use the "Edit Class" command to add all the required attributes.

Let's start modeling the user interface for our mobile app. Move to the App View, then click "View Container", select the "Screen" item and place it in the work area. Type a name for it, such as "Employee". Now, select the "List" item from the toolbar section related to "View Containers" and place it in the screen. Type a name for the list, then define the Data Binding for it: press the "Select" button and choose the "Contact" class in the opening dialog. Then press the "OK" button. Now define set the "Display Attribute" property, then set a sort criteria for the displayed attributes.

In order to add an employee to the contacts we need to use an "Action". Let's add an "Action" to the IFML model: select the "Action" item from the toolbar and place it in the work area.

In order to let the user select an employee from the list and trigger the action, let's use an "On Select Event" with a "Navigation Flow". Select the "Navigation Flow" item from the toolbar section related to "Flows" and click first on the "List" component and then on the action. Then write a name for the event.

An "Action" is a container of operations and these operations should be defined in a dedicated section of the model. Let's open the "Action Definitions" View to create the "Create Contact" action definition. Then double-click on the action definition to open it. In order to add an employee to the device contacts, let's use the "Contacts" operation. Select the "Contact" operation from the toolbar section related to "Utility Components" and then place it in the action definition. Write a name for it such as "Save Contact". The "Contacts" operation interacts with the native device contacts and it is capable of add and pick contacts. In our example the operation uses the employee information parameters in order to create a new item in the device contacts. As you can see, by default the "Mode" property is set to "Save Contact". In this case we can leave it as it is.

In order to state that the "Contacts" operation must be the first operation to be executed, let's use a Success Flow. Select the "Success Flow" item from the toolbar and click first on the "Input Port" and then on the "Contacts" operation.

In order to provide the required input to the "Contacts" operation let's add the "Input Port Parameters" to the "Input Port" which represents the entry point. Right-click on the Input Port and let's use the "Input Port Wizard..." for this purpose. Select the desired parameters and press the "Finish" button.

The Input Port Parameters we have just created are now visible next to the Input Port and they are automatically bound with the corresponding input parameters provided by the "Save Contact" Contact Operation. Finally let's connect the Operation with the Success and Error Port depending on its result. Click on the "Flows" section of the toolbar, choose the "Success Flow" item, click on the "Contacts" operation and then on the Success Port. Click on the "Flows" section of the toolbar, choose the "Error Flow" item, click on the "Contacts" operation and then on the Error Port.

The "Contacts" operation supports an additional Success Flow when the user cancels the operation. Let's model an additional Success Port to handle this specific case. Click on the "Port Definitions" section of the toolbar, choose the "Success Port" item and place it on the right border of the work area. Type a name for the Success Port, such as "Cancel".

When the user press the "Cancel" button the execution must exit through the "Cancel" success port. Let's use a new Success Flow for this purpose, then choose the "Cancel" option for the "Code" property. After the execution of the "Contacts" operation, if an error occurs then the Action Definition must exit through the Error Port. Let's use an Error Flow for this purpose.

Now that the Action Definition is complete, let's use it in our IFML model. Move back to the App View and select the Action. Press the "Select" button next to the "Action Definition" property and choose the "Create Contact" action definition. The Navigation Flow also provides information to the Action. Let's define the parameter binding. Double-click on the navigation flow, then use the "Guess Binding" button to define the binding.

Let's use another screen to display the result of the "Create Contact" execution. Select a Screen from the toolbar and place it in the App View. Type a name for it, such as "Feedback".

Let's use a "Message" view component to display a feedback message in the screen. Select the "Message Component" and place it in the "Feedback" screen.

If the execution of the "Create Contact" action exit through the Default Success Port a success message has to be displayed in the "Feedback" screen. Let's use a Navigation Flow for this purpose. Let's define the parameter binding for the Navigation Flow. Double-click on the flow, then write a feedback message in the dialog. If the execution of the "Create Contact" Action exit through the "Cancel" Success Port the user must be redirected to the Home screen. Let's use another Navigation Flow for this purpose.

How to Emulate with WebRatio Developer App

Let's now generate the project to emulate the mobile application. Press the "Generate and Run" button. Using the WebRatio Developer App, press the "Scan QR Code" button and capture the generated QR code available in the browser page. Once you reach the Home Screen, select an employee to add to Contacts. The default device Contacts app will be opened. Now press the "Done" button to confirm. The selected contact will be saved in your device contacts.

Pick Contact

Now we want to modify our Mobile Project in order to allow the user to pick an existing contact from the default device contacts app. Since we want to display a button in the "Employees" screen, let's start adding a toolbar in the screen. Select the "Toolbar" item from the toolbar section related to View Container, and place it in the "Employee" screen. Write a name for it, such as "Button Bar".

In order to pick a contacts we need to use an "Action". Let's add an "Action" to the IFML model. In order to let the user trigger the action, let's use an "On Select Event" with a "Navigation Flow". Select the Navigation flow item from the toolbar section related to Flows and click first on the Toolbar and then on the action. Then write a name for the event.
Let's open the Action Definitions View to create the "Pick Contact" action definition. We can obtain our "Pick Contact" action sefinition starting from a copy of the "Create Contact" action definition. Copy the "Create Contact" action definition and paste it in the action definitions list. Rename the copy with a new name, such as "Pick Contact". Then double-click on the Action Definition to open it.

Since the "Pick Contact" action definition differ from the "Create Contact" action definition, we need to make some changes. In this case we don't need any Port Definition Parameter, we can delete all the ones we have inherited from the "Create Contact" action definition. In this case we don't need any Port Definition Parameter, we can delete all the ones we have inherited from the "Create Contact" action definition. Expand the "Input Port" node in the Outline View. Right-click on the selected parameters and choose the "Delete" option, then confirm the deletion, by pressing "Yes".

Since we removed the Port Definition Parameters, we need to reset the corresponding parameter binding defined on the Success Flow connecting the Input Port with the "Contact" operation.  Double-click on the Success Flow, check the "Enable Default Binding" property and press the "OK" button.

We need to configure the "Contacts" operation in order to set it in the read mode. Select the "Contacts" operation, change its name with "Pick Contact". Set the "Mode" property with the "Pick Contact" option.

Finally, we need to define a set of Port Definition Parameters in order to pass in output all the information returned by the "Pick Contact" operation. Right-click on the Default Success Port, choose the "Success Port Wizard..." option and select the desired parameters. Then press the "Finish" button.

Now that the Action Definition is complete, let's use it in our IFML model.
Move back to the App View, select the Action and press the "Select" button next to the "Action Definition" property. Then choose the "Pick Contact" action definition and press the "OK" button. Let's use a "Form" component placed in the "Feedback" screen. We will preload the "Form" component with the information returned by the "Pick Contact" action. Select the "Form" item from the toolbar section related to View Components and place it in the "Feedback" screen. Let's use the "Edit Form" command to add the fields we need into the "Form" component. If the execution of the "Pick Contact" action exit through the Default Success Port the returned contact will be preloaded in the "Form" component. Let's use a Navigation Flow for this purpose, then define the parameter binding for the Navigation Flow. If the execution of the "Pick Contact" action exit through the "Cancel" success port the user must be redirected to the Home screen. Let's use another Navigation Flow for this purpose. Now let's define the layout for the "Pick Contact" button, in order to make it visible in the "Employees" screen. Drag the "Pick Contact" event and drop it in the Main Grid.

How to Emulate with WebRatio Developer App

Once our Mobile Project is complete, let's test the "CRM" mobile app. Press the "Generate and Run" button. Access to the mobile app using the WebRatio Developer App. In the Home Screen, press the "Pick Contact" button, the device Contacts app will be opened. Select a contact from the list, then the information related to the selected contact will be preloaded in the Form.