PhoneGap Build

93

Chapter 5

Using Contacts

In this chapter, we will cover:

◾ Understanding the PhoneGap Contacts Application Programming Interface (API)

◾ Creating Contacts manually

◾ Reading Contacts

◾ Adding Contacts

◾ Adding detailed information of the Contacts

◾ Deleting and updating Contacts

All mobile devices, whether an iPhone, Android, BlackBerry, Windows Phone, or Palm webOS,

each has a built-in Contacts database that is used for keeping information of desired people. at is,

the name, address, phone number, e-mail address, and so on, of the desired people can be kept in the

Contacts database. ese contacts are then used for sending e-mails, sending SMS, and remembering

phone numbers, addresses, and so on. Different phone manufacturers may use different contact fields

to store contact information. To resolve this difference and develop code that can be uniformly applied

to access and manage contacts on different mobile devices, the PhoneGap Contacts API is used.

e PhoneGap Contacts API provides an interface to create, list, edit, copy, and delete contact

rows from the device’s Contacts database. When we create a contact, its information, that is, its

name, e-mail addresses, phone numbers, photos, and so forth, are maintained in the form of prop-

erties. e properties that describe a contact are shown in Table 5.1.

Contacts can be created, saved, searched, and removed from the device Contacts database. e

methods used for this purpose are given below:

◾ Clone—Returns a new Contact object that is a copy of the calling object. e id property

of the returned Contact object is set to null.

◾ Remove—Removes the specified contact from the device Contacts database.

◾ Save—Saves a new contact to the device Contacts database. If the id of the contact being

saved already exists, the method updates the existing contact.

◾ Find—Searches the device Contacts database and returns an array of Contact objects com-

prising specified fields.

94  ◾  PhoneGap Build

Being frequently used, let us talk about the find method in detail. e format of using the

find method is given below:

navigator.contacts.find(contactFields, contactSuccess, contactError,

contactFindOptions);

where:

◾ contactFields—Specifies the fields whose values we wish to see in the resulting Contact

objects. If * is supplied in this parameter, all fields will be returned. If a zero-length param-

eter is supplied, then only the id field will be returned. Remember, the specified fields are

returned as properties of the Contact objects.

◾ contactSuccess—A success callback function that is invoked with the contacts that are

returned from the Contacts database.

◾ contactError—An optional error callback function that is invoked if any error occurs.

◾ contactFindOptions—An optional parameter that specifies the options to filter the

contacts. Basically, this parameter contains properties used to filter the results of a con-

tacts.find operation. Below are the two properties that this parameter comprises:

− filter—Represents the search string used to find contacts.

− multiple—Boolean value that determines if the find operation should return mul-

tiple contacts. Its default value is false.

Table5.1 A Brief Description of the Contact’s Properties

Properties Description

id

Represents a unique identifier of a contact.

displayName

Represents the name of the contact displayed to the users.

name

Represents an object containing all components of the contact’s name.

nickname

Represents a casual name of the contact.

phoneNumbers

Represents an array of all the contact’s phone numbers.

e-mails

Represents an array of all the contact’s e-mail addresses.

addresses

Represents an array of all the contact’s addresses.

ims

Represents an array of all the contact’s IM addresses.

organizations

Represents an array of all the contact’s organizations.

birthday

Represents the birth date of the contact.

note

Represents a note about the contact.

photos

Represents an array of the contact’s photos.

categories

Represents an array of all the contact’s user-defined categories.

urls

Represents an array of Web pages associated with the contact.