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:
CloneReturns 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.
SaveSaves a new contact to the device Contacts database. If the id of the contact being
saved already exists, the method updates the existing contact.
FindSearches 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:
contactFieldsSpecifies 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.
contactSuccessA 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.
contactFindOptionsAn 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:
filterRepresents the search string used to find contacts.
multipleBoolean 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.

Get PhoneGap Build now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.