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

What are we going to build?

In this tutorial, you’ll learn how to build an app that lists device contacts via button press.

The app will look like:
009-ReadyApp

Before you begin

Tutorial level: intermediate.

Apache Cordova (PhoneGap)

Apache Cordova (PhoneGap) is automatically included when you create a new project in Appery.io. The contacts component used in Appery.io is the contacts component from Apache Cordova.

Note: To learn more about the component, and any other settings and options, please go to the contacts documentation page.

Creating a new app

Create a new app in the Appery.io app builder; from the Apps page, enter an app name and click “Create”. You’ll see a start page.

Creating the UI

The UI will look like:
000-UI

First, place an Input component on the page, and rename to query_input. Also, type “enter query here…” in the Placeholder field:
001-InputProperties

Place the Button component on the page, and rename it to search_button. Place the List component on the page and rename it to contacts_list. Reduce number of list items to 1, rename list item to contacts_item. Place the Grid component over the List component. Place four Label components into each cell:
002_List

The top- and bottom-left labels are used for titles. Give them any names you want, or leave the default values.

The top- and bottom-right labels don’t contain any text, and have names contact_name and phone_number, respectively.

Adding the contacts service

To add the contacts service:

  1. From Projects view: Create New > Service > Contacts, enter name ContactsService and click “Create Service.” The service will be listed under the Services folder.
  2. If you open the service, you’ll see that everything has been preconfigured:
    003-Preconfigured

Binding the contacts service

  1. Open the Data tab.
  2. For datasource, select Device > ContactsService > Add. The contacts service will be added to the page. Name it contacts_service:
    004-AddedService
  3. Click “Mapping” in front of “Before send”.
  4. There are several request options you can see in the Mapping editor:
    005-BeforeSendParameters
    Take a look at the meaning of these parameters:

    • filterstring parameter, determines which records must be shown. It can retrieve as input any text data as the contact name, phone number, or even the e-mail. For example, the Dan value will show only contacts with this occurrence.
    • multiple Boolean parameter, determines if the find operation returns multiple contacts.
    • fieldsstring parameter, determines in which fields the search operation must be performed. Fields must be separated by a space (not a comma). Only specified fields will be returned as a result. This string means that the search will be performed only in these fields and only these fields will be returned: phoneNumbers, name, email. The fields parameter must contain at least one field or * symbol. List of possible fields:
      1. name
      2. phoneNumbers
      3. emails
      4. addresses
      5. IMs
      6. organizations
      7. categories
      8. URLs
  5. To take the value for filter from the page, create the following mapping:
    006-BeforeSendMapping
  6. Open the Success event Mapping editor.
  7. To display the contact name and phone number, create the following mapping, and save:
    007-SuccessMapping

Launching the contacts

  1. Open the Design tab.
  2. Select the button, open the Events tab, and add the following event:
    search_button > Click > Invoke service > contacts_service, and click “Add Event.”
  3. Save:
    008-InvokeService

Since we’re invoking a native component, this app has to be tested as a hybrid app, or installed on the device. Testing in the browser won’t work. Remember to search for a contact you already have.

The final app will look like:
009-ReadyApp

Android

Testing on Android is relatively simple, since you can quickly install any app on your device.

Testing options:

  1. Use the Appery.io Mobile Tester app. It’s an app that allows you to launch any app created in Appery.io as a hybrid app. You can find it in the Google Play Store.
  2. Build the Android binary and install it your device. When the build is completed, you’ll see a QR code. Scanning the QR code will download the app to your phone. You can also email the app to your device.

iOS

iOS options:

  1. Build the app and install it on your device.
  2. You have the option to run the Appery.io Mobile Tester for iOS. However, it requires building the app and installing it on your device.