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

Introduction

In this tutorial you will learn how to use the Appery.io Contacts Service based on the Cordova API in an AngularJS app.

The app will look like:

Before you begin

Tutorial level: intermediate.

Prerequisites: an Appery.io account.

Creating from the backup

You can build this app app by following our step-by-step tutorial below  or create it from the backup.

To create an app from the backup:

  1. Click Create new app.
  2. Type an app name.
  3. Click From backup and select the project backup file.
  4. Click Create.

Apache Cordova (PhoneGap)

Apache Cordova (PhoneGap) is automatically included when you create a new project in Appery.io. The Contacts Plug-in component used in Appery.io is the cross-platform Cordova  Contacts plug-in.

To learn more about the component, its objects and methods or any other settings and options, please visit the Apache Cordova plug-in contacts page.

Cordova contact object vs Appery.io contact object

An Appery.io contact object is just a JSON object that describes contact. It can’t be used in save and remove services.

A Cordova contact object is a Javascript object with methods. It can be used in any of services. But it can onlybe created by Contact_create or Contact_clone services.

There is no difference in the structure of these objects.

If the documentation does not specify the object type, than either of them can be used.

Services

Appery.io Contacts plug-in contains following services:

Contact_create

Creates contact object. It doesn’t save it to the device’s contacts list.

Request params: contact object. All fields are optional.

Response params: Cordova contact object.

Contact_find

Finds contacts using filter.

Request params:

  • options.filter (String) – The search string. (Default: "").
  • options.multiple (Boolean) – Determines if the find operation returns multiple contacts. (Default: false).

  • params.desiredFields (String) – Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. (Default: "*")

Response params: list of Cordova contact objects.

Contact_clone

Returns a new Cordova contact object that is a deep copy of the calling object, with the id property set to null.

Request params: contact object. All fields are optional.

Response params: Cordova contact object.

Contact_save

Saves a new contact to the device’s contacts database, or updates an existing contact if a contact with the same ID already exists.

Request params: Cordova contact object. All fields are optional.

Response params: Cordova contact object.

Contact_remove

Removes the contact from the device’s contacts database, otherwise executes an error callback with a ContactError object.

Request params: Cordova contact object. All fields are optional.

No response.

Contact_pick

Launches the Contact Picker to select a single contact.

No request params.

Response params: Cordova contact object.

Models

By default, the plug-in also contains the following models (Project > Model):

aioContact

  • id: A globally unique identifier.
  • displayName: The name of the contact, suitable for display to end users.
  • name: An object containing all components of a persons name.
  • nickname: A casual name by which to address the contact.
  • phoneNumbers: An array of all the contact’s phone numbers.
  • emails: An array of all the contact’s email addresses.
  • addresses: An array of all the contact’s addresses.
  • ims: An array of all the contact’s IM addresses.
  • organizations: An array of all the contact’s organizations.
  • birthday: The birthday of the contact.
  • note: A note about the contact.
  • photos: An array of the contact’s photos.
  • categories: An array of all the user-defined categories associated with the contact.
  • urls: An array of web pages associated with the contact.

aioContactField

  • type: A string that indicates what type of field this is, home for example.
  • value: The value of the field, such as a phone number or email address.
  • pref: Should be set to true if this ContactField contains the user’s preferred value.

aioContactAddress

  • pref: Set to true if this ContactAddress contains the user’s preferred value.
  • type: A string indicating what type of field this is, home for example.
  • formatted: The full address formatted for display.
  • streetAddress: The full street address.
  • locality: The city or locality.
  • region: The state or region.
  • postalCode: The zip code or postal code.
  • country: The country name.

aioContactOrganization

  • pref: Should be set to true if this ContactOrganization contains the user’s preferred value.
  • type: A string that indicates what type of field this is, home for example.
  • name: The name of the organization.
  • department: The department the contract works for.
  • title: The contact’s title at the organization.

aioContactName

  • formatted: The complete name of the contact.
  • familyName: The contact’s family name.
  • givenName: The contact’s given name.
  • middleName: The contact’s middle name.
  • honorificPrefix: The contact’s prefix (example Mr. or Dr.).
  • honorificSuffix: The contact’s suffix (example Esq.).

Creating the app

Design

1. Create a new Appery.io Bootstrap & AngularJS or Ionic & AngularJS project. You will get two default pages: index and Screen1.

2. Define the Header for the index page with Text = Contacts.

3. Add a Button to the right Header ButtonText = HomeWidth = Inline, for Attribute, set: navigate-to = main.

4. Now, add an Icon: Position = left, Styleion-ios-home .

3. Switch to Screen1 and rename it to Main, and create the following UI consisting of 2 Button components.

Set the next properties for the first one: Text = Find contactsWidth = Full, for Attribute, set: navigate-to = find; for the second: Text = Create new contact, Width = Fullnavigate-to = create respectively.

4. CREATE NEW > Page. Name it Create.

  • Add the Grid with four Grid Row components having two Grid Cell components each.
  • Drag and drop a Text component to each left Grid Cell of the Grid Rows and an Input to each Grid Cell on the right.
  • Configure the Text components with the next Text properties: Name, Family Name, Display Name, and Phone.
  • For the Inputs, define their ng-model fields as: $parent.name.givenName, $parent.name.familyName, $parent.displayName, and  $parent.phoneNumber correspondingly.
  • Lastly, place another Button: Text = Save, Width = Full, and ng-click = createContact().

5. Now, create another page: Find and define the following UI:

  • Place a Grid component with two Grid Cells.
  • Add an Input to the left Grid Celland define: Placehoder = Filter... , ng-model$parent.query.
  • Drag and drop a Button to the Cell on the right:  Text = cleared, Width = Inline, and ng-click = findContacts(). Add a search IconPosition = left, Styleion-ios-search-strong.
  • Place another Grid with two Grid Rows having two Grid Cells each.
  • Drag a Text component to each of the four Cells.
  • Configure the Text components (from left to right) with the next Text properties: Name, Phone, {{contact.displayName}}, and {{phone.value}}.
  • Define the lastText component: ng-repeat = phone in contact.phoneNumbers.
  • Add the attribute to the second row: ng-repeat = contact in contacts.

FindPage

If you are new to using AngularJS components, read here and here.

6. Lastly, go to Project > Routing and set the following routing:

Now, let’s create services and variables and bind them with UI components.

Adding a contacts plug-in

To add the Contacts services:

1. From Projects view; CREATE NEW > From Plug-in  > Apperyio Contacts Service, and click Import selected plug-ins. New services will be listed under the Services folder.

2. If you open any of the services, you’ll see that everything has been preconfigured:

Scope

1. To add the following variables, go to SCOPE:

  • of theFind page: contacts (Type = aioContactsArray) and query (Type = String);
  • of theCreate page: name (Type = aioContactName), displayName, phoneNumber (Type of both = String), contact (Type = aioContact), and phoneNumbers (Type = aioContactFieldsArray).

After native services have been added to the app, they can be called. Invoking a native service is very similar to invoking a REST service.

2.To call the added services, first switch to the Find page, Functions view, click Edit for the init function and paste this code:

3.Now, add a new Scope function for the Find page: findContacts.

4. Next, click Edit for the findContacts function, opening the function editor.

5. In the editor, click the arrow to filter snippets, select Invoke service, and click Insert snippet.

6.Then, delete the text service_name in the code and  click <CTRL> + <SPACE> to select Contact_find.

7. After auto completing, the service is added to the function code and you can click response Mapping to map the service to the page:MappingFind

Clicking on the upper Mapping button defines the service request, while clicking on the lower one defines the service response.

Add the next code after var requestData = {:

The final result:

7. Switch to the Create page, then go to SCOPE and click Edit for the init function to paste this code:

8. Now, create two more functions: createContact and clearVars.

9. Click Edit for the createContact function and add the following code to the top:

10. Now, invoke the first service: Contact_create.

11. After auto completing, the service is added to the function code and you can click Mapping to map the service to the page.

12. Now, click the upper Mapping button and create this:

13. Second, create the following mapping for the Contact_create service response:CreateMapping2

14. Now, invoke another service: Contact_save and create the next mapping for the Contact_save service request:CreateMapping3

Clicking on the upper service mapping button defines the service request while the lower one defines the service response.

Finally, replace the rest of the code starting from before the last mapping button with the following:

The resulting code should look similar to this:

15. The last function to edit is clearVars. Add this code to it and save:

Testing options

Since we’re invoking a native component, this app needs to be tested as a hybrid app or installed on the device:Result

Android

Android 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. 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.
  2. Build the app and install it on your device.