The Contacts API

You can easily access the contact information stored on a device using the PhoneGap API. The Contacts API is an implementation of the W3C's Pick Contacts Intent API (an intent that enables access to a user's address book service from inside a web application). You can read more about the W3C specifications at http://www.w3.org/TR/contacts-api/).

In order to allow your app to access and manipulate the contacts stored on the device, you have to update the specific platform configuration files. The following table lists the information you need to add to the configuration files for Android, iOS, and Windows Phone apps. For a complete list of all the supported platforms refer to the online documentation at http://docs.phonegap.com/en/edge/cordova_contacts_contacts.md.html#Contacts.

Platform

Configuration file

Content

Android

app/res/xml/config.xml 

<plugin name="Contacts" value="org.apache.cordova.ContactManager" />
 

app/AndroidManifest.xml 

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

iOS

config.xml 

<plugin name="Contacts" value="CDVContacts" />

Windows Phone

Properties/WPAppManifest.xml 

<Capabilities>
    <Capability Name="ID_CAP_CONTACTS" />
</Capabilities>

In order to start to interact with the device contacts, you can use the create or the find methods defined in the contacts object stored in the navigator one:

var contact = navigator.contacts.create(properties); 
navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

In order to better understand how these methods work, let's explore the most relevant objects that are involved with them: Contact, ContactName, ContactField, ContactFindOptions, and ContactError.

The ContactName object

The ContactName object is used in the PhoneGap framework in order to store all the details of a contact name. The object is stored in the property name of the object Contact.

The properties of the ContactName object are all strings and are self-explanatory:

  • formatted represents the complete name of the contact.
  • familyName represents the contact's family name.
  • givenName represents the contact's given name.
  • middleName represents the contact's middle name.
  • honorificPrefix represents the contact's prefix (e.g., Mr. or Dr.).
  • honorificSuffix represents the contact's suffix (e.g., Esq.).

Tip

Until Version 2.4 the formatted property of the ContactName object is partially supported on Android and iOS. The property will return several data concatenated; it also doesn't store anything on the device.

The ContactField object

The ContactField object is a generic object used in the PhoneGap framework in order to represent a field of the Contact object. The generic nature of this object makes it reusable across several fields.

The properties of the ContactFiled object are:

  • type: a string that represents the type of field; possible values are home, work, mobile, and so on.
  • value: a string representing the value of the field such as a phone number or e-mail address.
  • pref: a Boolean value that indicates whether in a specific field the user preferred value is returned.

Tip

When the ContactField object is used in the photos property of the Contact object the type property represents the type of a returned image (for example, a URL or a Base64-encoded string).

The ContactAddress object

The ContactAddress object is the object stored in the addresses property of the Contact object. The addresses property is an array so that multiple addresses can be associated with each contact.

The properties of the ContactAddress object are:

  • pref: a Boolean that indicates whether the returned ContactAddress is the preferred value of the user for the ContactAddress object
  • type: a string that indicates what type of address is stored in the ContactAdress object (for example, home, and office)
  • formatted: a string that represents the complete address formatted for display
  • streetAddress: a string that represents the complete street address
  • locality: a string that represents the city or locality that is part of the ContactAddress object
  • region: a string representing the state or region that is part of the ContactAddress object
  • postalCode: a string that represents the zip code or postal code associated with the locality stored in the ContactAddress object
  • country: a string representing the name of the country stored in the ContactAddress object

Tip

There is a limitation in Android 2.x (i.e., the pref property is not supported) and several on Android 1.x. Also, iOS does not support the formatted property. Always refer to the online documentation to verify the status of the support for the ContactAddress object.

The ContactOrganization object

The ContactOrganization object represents all the details of a company, organization, and so on that the stored Contact belongs to. The object is stored in the array contained in the organizations property of the Contact object.

The properties of the ContactOrganization object are:

  • pref: a Boolean that indicates if the returned ContactOrganization object is the preferred value of the user for the ContactOrganization object
  • type: a string that indicates what type of address is stored in the ContactOrganization object (for example, work and other)
  • name: a string that represents the name of the organization stored in the ContactOrganization object
  • department: a string that represents the department of the organization the contact works for
  • title: a string that represents the contact's title in the organization

The properties name, department, and title are partially supported on iOS; the pref and type properties are badly supported on Android 1.x and Android 2.x.

The Contact object

The Contact object represents all the details of a contact stored in the device database. A Contact object can be saved, removed, and copied from the device contact database using the methods save, remove, and clone defined on the object itself. The save and remove methods accept two arguments in order to handle the success and the failure of the save or remove operation:

var contact = navigator.contacts.create({'displayName': 'Giorgio'});

contact.save(onContactSaved,onContactSavedError);contact.remove(onContactRemoved, onContactRemovedError);

The error handlers receive the same ContactError object as an argument; the success handlers receive the saved contact or a snapshot of the current database when a contact is successfully removed.

The ContactError object contains in the code property the information about the occurred error. The values that can be returned are:

  • ContactError.UNKNOWN_ERROR
  • ContactError.INVALID_ARGUMENT_ERROR
  • ContactError.TIMEOUT_ERROR
  • ContactError.PENDING_OPERATION_ERROR
  • ContactError.IO_ERROR
  • ContactError.NOT_SUPPORTED_ERROR
  • ContactError.PERMISSION_DENIED_ERROR

When creating a new Contact object, you can define one by one the contact properties or pass them as an object when calling the create method. The properties of the Contact object are:

  • id: a string used as a globally unique identifier
  • displayName: a string that represents the name of the Contact object for display to end users
  • name: an object containing all the information of a contact name; the object used to store this information is the ContactName
  • nickname: a string that represents the casual name of a contact
  • phoneNumbers: an array of all the contact's phone numbers; the array items are instances of the ContactField object
  • emails: an array of all the contact's e-mail addresses; the array items are instances of the ContactField object
  • addresses: an array of all the contact's addresses; the array items are instances of the ContactAddresses object
  • ims: an array of all the contact's instant messages accounts; the array items are instances of the ContactField object
  • organizations: an array of all the organizations the contact belongs to; the array items are instances of the ContactOrganization object
  • birthday: a Date object that represents the birthday of the contact
  • note: a string that represents a note about the contact
  • photos: an array of all the contact's photos; the array items are instances of the ContactField object
  • categories: an array of all the contact's defined categories; the array items are instances of the ContactField object
  • urls: an array of all the web pages associated with the contact; the array items are instances of the ContactField object

The Contact object properties are not fully supported across all platforms. In fact operating system fragmentation makes it difficult to handle this information consistently.

For instance, the properties name, nickname, birthday, photos, categories, and urls are not supported on Android 1.x. Likewise the categories property is supported neither on Android 2.x. nor on iOS.

On iOS, the items returned in the photos array contain a URL that points to the app's temporary folder. This means that this content is deleted when the app exits and that you have to handle it if you want the user to find the app in the same status he/she left it. The displayName property is not supported on iOS and will be returned as null unless there is no ContactName defined. If the ContactName object is defined, then a composite name or nickname is returned.

Filtering contact data

I already mentioned the find method available on the navigator.contacts object. Using this method an app can find one or multiple contacts in the device's contact database. The find method accepts four arguments. The first one is an array that contains the name of the fields of the Contact object that have to be returned. The second and the third are the success and error handlers. The last one represents the filtering options you want to apply to the current research.

In order to apply a filter to the current search, it is enough to instantiate a new ContactFindOptions object and populate the filter and multiple properties. The filter property is a case-insensitive string that will act as a filter on the fields of the Contact objects returned by the find method. The multiple property is false by default and is the one to use in order to receive multiple Contact objects in the success handler.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.118.227.69