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. Diﬀerent phone manufacturers may use diﬀerent contact ﬁelds
to store contact information. To resolve this diﬀerence and develop code that can be uniformly applied
to access and manage contacts on diﬀerent 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 speciﬁed 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 speciﬁed ﬁelds.
94 ◾ PhoneGap Build
Being frequently used, let us talk about the find method in detail. e format of using the
ﬁnd method is given below:
navigator.contacts.find(contactFields, contactSuccess, contactError,
◾ contactFields—Speciﬁes the ﬁelds whose values we wish to see in the resulting Contact
objects. If * is supplied in this parameter, all ﬁelds will be returned. If a zero-length param-
eter is supplied, then only the id ﬁeld will be returned. Remember, the speciﬁed ﬁelds 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 speciﬁes the options to ﬁlter the
contacts. Basically, this parameter contains properties used to ﬁlter the results of a con-
tacts.find operation. Below are the two properties that this parameter comprises:
− filter—Represents the search string used to ﬁnd contacts.
− multiple—Boolean value that determines if the ﬁnd operation should return mul-
tiple contacts. Its default value is false.
Table5.1 A Brief Description of the Contact’s Properties
Represents a unique identiﬁer of a contact.
Represents the name of the contact displayed to the users.
Represents an object containing all components of the contact’s name.
Represents a casual name of the contact.
Represents an array of all the contact’s phone numbers.
Represents an array of all the contact’s e-mail addresses.
Represents an array of all the contact’s addresses.
Represents an array of all the contact’s IM addresses.
Represents an array of all the contact’s organizations.
Represents the birth date of the contact.
Represents a note about the contact.
Represents an array of the contact’s photos.
Represents an array of all the contact’s user-deﬁned categories.
Represents an array of Web pages associated with the contact.