Contact

Contains properties that describe a contact, such as a user's personal or business contact.

Properties

  • id: A globally unique identifier. (DOMString)
  • displayName: The name of this Contact, suitable for display to end-users. (DOMString)
  • name: An object containing all components of a persons name. (ContactName)
  • nickname: A casual name to address the contact by. (DOMString)
  • phoneNumbers: An array of all the contact's phone numbers. (ContactField[])
  • emails: An array of all the contact's email addresses. (ContactField[])
  • addresses: An array of all the contact's addresses. (ContactAddresses[])
  • ims: An array of all the contact's IM addresses. (ContactField[])
  • organizations: An array of all the contact's organizations. (ContactOrganization[])
  • birthday: The birthday of the contact. (Date)
  • note: A note about the contact. (DOMString)
  • photos: An array of the contact's photos. (ContactField[])
  • categories: An array of all the contacts user defined categories. (ContactField[])
  • urls: An array of web pages associated to the contact. (ContactField[])

Methods

  • clone: Returns a new Contact object that is a deep copy of the calling object, with the id property set to null.
  • remove: Removes the contact from the device contacts database. An error callback is called with a [ContactError](../ContactError/contactError.html) object if the removal is unsuccessful.
  • save: Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.

Details

The Contact object represents a user contact. Contacts can be created, saved to, or removed from the device contacts database. Contacts can also be retrieved (individually or in bulk) from the database by invoking the [contacts.find](../contacts.find.html) method.

Note: Not all of the above contact fields are supported on every device platform. Please check each platform's Quirks section for information about which fields are supported.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS

Save Quick Example

function onSuccess(contact) {
	alert("Save Success");
};

function onError(contactError) {
	alert("Error = " + [contactError](../parameters/contactError.html).code);
};

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber"; 		//specify both to support all devices

// populate some fields
var name = new [ContactName](../ContactName/contactname.html)();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// save to device
contact.save(onSuccess,onError);

Clone Quick Example

// clone the contact object
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);

Remove Quick Example

function onSuccess() {
    alert("Removal Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// remove the contact from the device
contact.remove(onSuccess,onError);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.6.1.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova is ready
    //
    function onDeviceReady() {
	    // create
	    var contact = navigator.contacts.create();
		contact.displayName = "Plumber";
		contact.nickname = "Plumber"; 		//specify both to support all devices
		var name = new [ContactName](../ContactName/contactname.html)();
		name.givenName = "Jane";
		name.familyName = "Doe";
		contact.name = name;

		// save
		contact.save(onSaveSuccess,onSaveError);
		
		// clone
		var clone = contact.clone();
		clone.name.givenName = "John";
		console.log("Original contact name = " + contact.name.givenName);
		console.log("Cloned contact name = " + clone.name.givenName); 
		
		// remove
		contact.remove(onRemoveSuccess,onRemoveError);
    }
    
    // onSaveSuccess: Get a snapshot of the current contacts
    //
    function onSaveSuccess(contact) {
		alert("Save Success");
    }

    // onSaveError: Failed to get the contacts
    //
    function onSaveError(contactError) {
		alert("Error = " + [contactError](../parameters/contactError.html).code);
    }
    
    // onRemoveSuccess: Get a snapshot of the current contacts
    //
    function onRemoveSuccess(contacts) {
		alert("Removal Success");
    }

    // onRemoveError: Failed to get the contacts
    //
    function onRemoveError(contactError) {
		alert("Error = " + [contactError](../parameters/contactError.html).code);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X Quirks

  • categories: This property is not support by Android 2.X devices, and will always be returned as null.

Android 1.X Quirks

  • name: This property is not support by Android 1.X devices, and will always be returned as null.
  • nickname: This property is not support by Android 1.X devices, and will always be returned as null.
  • birthday: This property is not support by Android 1.X devices, and will always be returned as null.
  • photos: This property is not support by Android 1.X devices, and will always be returned as null.
  • categories: This property is not support by Android 1.X devices, and will always be returned as null.
  • urls: This property is not support by Android 1.X devices, and will always be returned as null.

BlackBerry WebWorks (OS 5.0 and higher) Quirks

  • id: Supported. Assigned by device when contact is saved.
  • displayName: Supported. Stored in BlackBerry user1 field.
  • nickname: This property is not supported, and will always be returned as null.
  • phoneNumbers: Partially supported. Phone numbers will be stored in BlackBerry fields homePhone1 and homePhone2 if type is 'home', workPhone1 and workPhone2 if type is 'work', mobilePhone if type is 'mobile', faxPhone if type is 'fax', pagerPhone if type is 'pager', and otherPhone if type is none of the above.
  • emails: Partially supported. The first three email addresses will be stored in the BlackBerry email1, email2, and email3 fields, respectively.
  • addresses: Partially supported. The first and second addresses will be stored in the BlackBerry homeAddress and workAddress fields, respectively.
  • ims: This property is not supported, and will always be returned as null.
  • organizations: Partially supported. The name and title of the first organization are stored in the BlackBerry company and title fields, respectively.
  • photos: - Partially supported. A single thumbnail-sized photo is supported. To set a contact's photo, pass in a either a Base64 encoded image, or a URL pointing to the image. The image will be scaled down before saving to the BlackBerry contacts database. The contact photo is returned as a Base64 encoded image.
  • categories: Partially supported. Only 'Business' and 'Personal' categories are supported.
  • urls: Partially supported. The first url is stored in BlackBerry webpage field.

iOS Quirks

  • displayName: This property is not supported by iOS and will be returned as null unless there is no ContactName specified. If there is no ContactName, then composite name, nickname or "" is returned for displayName, respectively.
  • birthday: For input, this property must be provided as a JavaScript Date object. It is returned as a JavaScript Date object.
  • photos: Returned Photo is stored in the application's temporary directory and a File URL to photo is returned. Contents of temporary folder is deleted when application exits.
  • categories: This property is not currently supported and will always be returned as null.