Contacts
The
contactsobject provides access to the device contacts database.
Methods
Arguments
Objects
- Contact
- ContactName
- ContactField
- ContactAddress
- ContactOrganization
- ContactAccount
- ContactFindOptions
- ContactError
contacts.create
Returns a new Contact object.
var contact = navigator.service.contacts.create(properties);
Description
contacts.create is a synchronous function that returns a new Contact object.
This method does not persist the Contact object to the device contacts database. To persist the Contact object to the device, invoke the Contact.save method.
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
var myContact = navigator.service.contacts.create({"displayName": "Test User"});
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
var myContact = navigator.service.contacts.create({"displayName": "Test User"});
myContact.gender = "male";
console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender");
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Create Contact</p>
</body>
</html>
contacts.find
Queries the device contacts database and returns one or more Contact objects, each containing the fields specified.
navigator.service.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);
Description
contacts.find is an asynchronous function that queries the device contacts database and returns an array of Contact objects. The resulting objects are passed to the contactSuccess callback function specified by the contactSuccess parameter.
Users must specify the contact fields to be used as a search qualifier in the contactFields parameter. Only the fields specified in the contactFields parameter will be returned as properties of the Contact objects that are passed to the contactSuccess callback function. A zero-length contactFields parameter will result in an array of empty Contact objects.
The contactFindOptions.filter string can be used as a search filter when querying the contacts database. If provided, a case-insensitive, partial value match is applied to each field specified in the contactFields parameter. If a match is found in a comparison with any of the specified fields, the contact is returned.
Parameters
-
contactFields: Contact fields to be used as search qualifier. Only these fields will have values in the resulting
Contactobjects. (DOMString[]) [Required] - contactSuccess: Success callback function that is invoked with the contacts returned from the contacts database. [Required]
- contactError: Error callback function. Invoked when error occurs. [Optional]
- contactFindOptions: Search options to limit and/or filter contacts. [Optional]
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
function onSuccess(contacts) {
alert('Found ' + contacts.length + ' contacts.');
};
function onError() {
alert('onError!');
};
// find all contacts with 'Bob' in any name field
var options = new ContactFindOptions();
options.filter="Bob";
var fields = ["displayName", "names"];
navigator.service.contacts.find(fields, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// find all contacts with 'Bob' in any name field
var options = new ContactFindOptions();
options.filter="Bob";
var fields = ["displayName", "names"];
navigator.service.contacts.find(fields, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log("Display Name = " + contacts[i].displayName);
}
}
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
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[])
- published: The date the contact was first added to the database. (DOMString)
- updated: The last date the contact was updated. (DOMString)
- birthday: The birthday of the contact. (DOMString)
- anniversary: The wedding anniversary of the contact. (DOMString)
- gender: The gender of the contact. (DOMString)
- note: A note about the contact. (DOMString)
- preferredUsername: The preferred username of the contact. (DOMString)
- photos: An array of all the contact's photos. (ContactField[])
- tags: An array of all the contacts user defined tags. (ContactField[])
- relationships: An array of all the contact's relationships. (ContactField[])
- urls: An array of web pages associated to the contact. (ContactField[])
- accounts: An array of accounts associated to the contact. (ContactAccount[])
- utcOffset: The offset from UTC of the contacts time zone. (DOMString)
- connected: Only true if the contact and the user have a bi-directional relationship. (DOMString)
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
ContactErrorobject 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 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 Widgets (OS 5.0 and higher)
Save Quick Example
function onSuccess(contacts) {
alert("Save Success");
};
function onError(contactError) {
alert("Error = " + contactError.code);
};
// create a new contact object
var contact = navigator.service.contacts.create();
contact.displayName = "Plumber";
// populate some fields
var name = new ContactName();
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 PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// create
var contact = navigator.service.contacts.create();
contact.displayName = "Plumber";
var name = new ContactName();
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(contacts) {
alert("Save Success");
}
// onSaveError: Failed to get the contacts
//
function onSaveError(contactError) {
alert("Error = " + contactError.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.code);
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
Android 2.X Quirks
-
published: This property is not support by Android 2.X devices, and will always be returned as
null. -
updated: This property is not support by Android 2.X devices, and will always be returned as
null. -
gender: This property is not support by Android 2.X devices, and will always be returned as
null. -
preferredUsername: This property is not support by Android 2.X devices, and will always be returned as
null. -
photos: This property is not support by Android 2.X devices, and will always be returned as
null. -
tags: This property is not support by Android 2.X devices, and will always be returned as
null. -
accounts: This property is not support by Android 1.X devices, and will always be returned as
null. -
utcOffset: This property is not support by Android 2.X devices, and will always be returned as
null. -
connected: 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. -
published: This property is not support by Android 1.X devices, and will always be returned as
null. -
updated: 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. -
anniversary: This property is not support by Android 1.X devices, and will always be returned as
null. -
gender: This property is not support by Android 1.X devices, and will always be returned as
null. -
preferredUsername: 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. -
tags: This property is not support by Android 1.X devices, and will always be returned as
null. -
relationships: 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. -
accounts: This property is not support by Android 1.X devices, and will always be returned as
null. -
utcOffset: This property is not support by Android 1.X devices, and will always be returned as
null. -
connected: This property is not support by Android 1.X devices, and will always be returned as
null.
BlackBerry Widgets (OS 5.0 and higher) Quirks
- id: Supported. Assigned by device when contact is saved.
- displayname: Supported. Stored in BlackBerry title field.
- name: Supported.
-
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.
-
published: This property is not supported, and will always be returned as
null. -
updated: This property is not supported, and will always be returned as
null. - birthday: Supported.
- anniversary: Supported.
-
gender: This property is not supported, and will always be returned as
null. - note: Supported.
-
preferredUsername: This property is not supported, and will always be returned as
null. -
photos: This property is not supported, and will always be returned as
null. -
tags: This property is not supported, and will always be returned as
null. -
relationships: This property is not supported, and will always be returned as
null. - urls: Partially supported. The first url is stored in BlackBerry webpage field.
-
accounts: This property is not supported, and will always be returned as
null. -
utcOffset: This property is not supported, and will always be returned as
null. -
connected: This property is not supported, and will always be returned as
null.
ContactAccount
Contains user account properties of a Contact object.
Properties
- domain: The top-most authoritative domain for this account. (DOMString)
- username: An alphanumeric user name. (DOMString)
- userid: A user ID number, usually chosen automatically, and usually numeric but sometimes alphanumeric. (DOMString)
Details
The ContactAccount object stores user account properties of a contact. A Contact object stores one or more accounts in a ContactAddress[] array.
Supported Platforms
- None
Quick Example
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].accounts.length; j++) {
console.log("User Name = " + contacts[i].accounts[j].username;
}
}
};
function onError() {
alert('onError!');
};
// find all contacts
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","accounts"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// find all contacts
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","accounts"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].accounts.length; j++) {
console.log("User Name = " + contacts[i].accounts[j].username;
}
}
}
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
ContactAddress
Contains address properties for a Contact object.
Properties
- formatted: The full address formatted for display. (DOMString)
- streetAddress: The full street address. (DOMString)
- locality: The city or locality. (DOMString)
- region: The state or region. (DOMString)
- postalCode: The zip code or postal code. (DOMString)
- country: The country name. (DOMString)
Details
The ContactAddress object stores the properties of a single address of a contact. A Contact object can have one or more addresses in a ContactAddress[] array.
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
// display the address information for all contacts
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].addresses.length; j++) {
alert("Formatted: " + contacts[i].addresses[j].formatted + "\n" +
"Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
"Locality: " + contacts[i].addresses[j].locality + "\n" +
"Region: " + contacts[i].addresses[j].region + "\n" +
"Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
"Country: " + contacts[i].addresses[j].country);
}
}
};
function onError() {
alert('onError!');
};
// find all contacts
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","addresses"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// find all contacts
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","addresses"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
// display the address information for all contacts
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].addresses.length; j++) {
alert("Formatted: " + contacts[i].addresses[j].formatted + "\n" +
"Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
"Locality: " + contacts[i].addresses[j].locality + "\n" +
"Region: " + contacts[i].addresses[j].region + "\n" +
"Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
"Country: " + contacts[i].addresses[j].country);
}
}
};
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
Android 1.X Quirks
-
streetAddress: This property is not support by Android 1.X devices, and will always return
null. -
locality: This property is not support by Android 1.X devices, and will always return
null. -
region: This property is not support by Android 1.X devices, and will always return
null. -
postalCode: This property is not support by Android 1.X devices, and will always return
null. -
country: This property is not support by Android 1.X devices, and will always return
null.
BlackBerry Widget (OS 5.0 and higher) Quirks
- formatted: Partially supported. Will return concatenation of all BlackBerry address fields.
- streetAddress: Supported. Will return concatenation of BlackBerry address1 and address2 address fields.
- locality: Supported. Stored in BlackBerry city address field.
- region: Supported. Stored in BlackBerry stateProvince address field.
- postalCode: Supported. Stored in BlackBerry zipPostal address field.
- country: Supported.
ContactField
Supports generic fields in a Contact object. Some properties that are stored as ContactField objects include email addresses, phone numbers, and urls.
Properties
- type: A string that tells you what type of field this is (example: 'home'). (DOMString)
- value: The value of the field (such as a phone number or email address). (DOMString)
-
primary: Set to
trueif thisContactFieldcontains the user's preferred value. (boolean)
Details
The ContactField object is a reusable component that is used to support contact fields in a generic fashion. Each ContactField object contains a value property, a type property, and a primary property. A Contact object stores several properties in ContactField[] arrays, such as phone numbers and email addresses.
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
// create a new contact
var contact = navigator.service.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555'-5432', true); // primary number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// save the contact
contact.save();
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// create a new contact
var contact = navigator.service.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555'-5432', true); // primary number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// save the contact
contact.save();
// search contacts, returning display name and phone numbers
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","phoneNumbers"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" +
"Value: " + contacts[i].phoneNumbers[j].value + "\n" +
"Primary: " + contacts[i].phoneNumbers[j].primary);
}
}
};
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
Android Quirks
-
primary: This property is not support by Android devices, and will always return
false.
BlackBerry Widget (OS 5.0 and higher) Quirks
- type: Partially supported. Used for phone numbers.
- value: Supported.
-
primary: This property is not supported, and will always return
false.
ContactFindOptions
Contains properties that can be used to limit or filter the results of a contacts.find operation.
Properties
- filter: The search string used to find contacts. (DOMString) (Default: "")
- multiple: Determines if the find operation should return multiple contacts. (Boolean) (Default: true)
- limit: The maximum number of contacts to return. Only used if multiple is true. (Number) (Default: MAXINT)
- updatedSince: Only return contacts updated since the date specified. (Date) (Default: "")
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
// success callback
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert(contacts[i].displayName);
}
};
// error callback
function onError() {
alert('onError!');
};
// specify contact search criteria
var options = new ContactFindOptions();
options.filter=""; // empty search string returns all contacts
options.multiple=true; // return multiple results
options.limit=10; // limit results to 10 contacts
filter = ["displayName"]; // return contact.displayName field
// find contacts
navigator.service.contacts.find(filter, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
// specify contact search criteria
var options = new ContactFindOptions();
options.filter=""; // empty search string returns all contacts
options.multiple=true; // return multiple results
options.limit=10; // limit results to 10 contacts
filter = ["displayName"]; // return contact.displayName field
// find contacts
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert(contacts[i].displayName);
}
};
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
ContactName
Contains name properties of a Contact object.
Properties
- formatted: The complete name of the contact. (DOMString)
- familyName: The contacts family name. (DOMString)
- givenName: The contacts given name. (DOMString)
- middleName: The contacts middle name. (DOMString)
- honorificPrefix: The contacts prefix (example Mr. or Dr.) (DOMString)
- honorificSuffix: The contacts suffix (example Esq.). (DOMString)
Details
The ContactName object stores name properties of a contact.
Supported Platforms
- Android 2.X
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert("Formatted: " + contacts[i].name.formatted + "\n" +
"Family Name: " + contacts[i].name.familyName + "\n" +
"Given Name: " + contacts[i].name.givenName + "\n" +
"Middle Name: " + contacts[i].name.middleName + "\n" +
"Suffix: " + contacts[i].name.honorificSuffix + "\n" +
"Prefix: " + contacts[i].name.honorificSuffix);
}
};
function onError() {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert("Formatted: " + contacts[i].name.formatted + "\n" +
"Family Name: " + contacts[i].name.familyName + "\n" +
"Given Name: " + contacts[i].name.givenName + "\n" +
"Middle Name: " + contacts[i].name.middleName + "\n" +
"Suffix: " + contacts[i].name.honorificSuffix + "\n" +
"Prefix: " + contacts[i].name.honorificSuffix);
}
};
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
BlackBerry Widgets (OS 5.0 and higher) Quirks
- formatted: Partially supported. Will return concatenation of BlackBerry firstName and lastName fields.
- familyName: Supported. Stored in BlackBerry lastName field.
- givenName: Supported. Stored in BlackBerry firstName field.
-
middleName: This property is not supported, and will always return
null. -
honorificPrefix: This property is not supported, and will always return
null. -
honorificSuffix: This property is not supported, and will always return
null.
ContactOrganization
Contains organization properties of a Contact object.
Properties
- name: The name of the organization. (DOMString)
- department: The department the contract works for. (DOMString)
- title: The contacts title at the organization. (DOMString)
- startDate: The date the contact started working with the organization. (DOMString)
- endDate: The date the contact finished working with the organization. (DOMString)
- location: The address of the location. (DOMString)
- description: A description of the role the contact has in the organization. (DOMString)
Details
The ContactOrganization object stores a contact's organization properties. A Contact object stores one or more ContactOrganization objects in an array.
Supported Platforms
- Android
- BlackBerry Widgets (OS 5.0 and higher)
Quick Example
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].organizations.length; j++) {
alert("Name: " + contacts[i].organizations[j].name + "\n" +
"Department: " + contacts[i].organizations[j].department + "\n" +
"Title: " + contacts[i].organizations[j].title + "\n" +
"Start Date: " + contacts[i].organizations[j].startDate + "\n" +
"End Date: " + contacts[i].organizations[j].endDate + "\n" +
"Location: " + contacts[i].organizations[j].location + "\n" +
"Description: " + contacts[i].organizations[j].description);
}
}
};
function onError() {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.service.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Get a snapshot of the current contacts
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].organizations.length; j++) {
alert("Name: " + contacts[i].organizations[j].name + "\n" +
"Department: " + contacts[i].organizations[j].department + "\n" +
"Title: " + contacts[i].organizations[j].title + "\n" +
"Start Date: " + contacts[i].organizations[j].startDate + "\n" +
"End Date: " + contacts[i].organizations[j].endDate + "\n" +
"Location: " + contacts[i].organizations[j].location + "\n" +
"Description: " + contacts[i].organizations[j].description);
}
}
};
// onError: Failed to get the contacts
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
Android 2.X Quirks
-
startDate: This property is not support by Android 1.X devices, and will always be returned as
null. -
endDate: This property is not support by Android 1.X devices, and will always be returned as
null.
Android 1.X Quirks
-
title: This property is not support by Android 1.X devices, and will always be returned as
null. -
startDate: This property is not support by Android 1.X devices, and will always be returned as
null. -
endDate: This property is not support by Android 1.X devices, and will always be returned as
null. -
location: This property is not support by Android 1.X devices, and will always be returned as
null. -
description: This property is not support by Android 1.X devices, and will always be returned as
null.
BlackBerry Widget (OS 5.0 and higher) Quirks
- name: Partially supported. The first organization name will be stored in the BlackBerry company field.
-
department: This property is not supported, and will always be returned as
null. - title: Partially supported. The first organization title will be stored in the BlackBerry jobTitle field.
-
startDate: This property is not supported, and will always be returned as
null. -
endDate: This property is not supported, and will always be returned as
null. -
location: This property is not supported, and will always be returned as
null. -
description: This property is not supported, and will always be returned as
null.
ContactError
A ContactError object is returned to the contactError callback when an error occurs.
Properties
- code: One of the predefined error codes listed below.
Constants
ContactError.UNKNOWN_ERRORContactError.INVALID_ARGUMENT_ERRORContactError.NOT_FOUND_ERRORContactError.TIMEOUT_ERRORContactError.PENDING_OPERATION_ERRORContactError.IO_ERRORContactError.NOT_SUPPORTED_ERRORContactError.PERMISSION_DENIED_ERROR
Description
The ContactError object is returned to the user through the contactError callback function when an error occurs.
contactSuccess
Success callback function that provides the Contact array resulting from a contacts.find operation.
function(contacts) {
// Do something
}
Parameters
-
contacts: The contact array resulting from a find operation. (
Contact)
Example
function contactSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log("Display Name = " + contacts[i].displayName;
}
contactError
Error callback function for contact functions.
function(error) {
// Handle the error
}
contactFields
Required parameter of the contacts.find method. Use this parameter to specify which fields should be included in the Contact objects resulting from a find operation.
["name", "phoneNumbers", "emails"]
contactFindOptions
Optional parameter of the contacts.find method. Use this parameter to limit and/or filter the contacts returned from the contacts database.
{
filter: "",
multiple: true,
limit: 5,
updatedSince: ""
};
Options
- filter: The search string used to filter contacts. (DOMString) (Default: "")
- multiple: Determines if the find operation should return multiple contacts. (Boolean) (Default: true)
-
limit: The maximum number of contacts to return. Only applied if multiple is
true. (Number) (Default: MAXINT) - updatedSince: Only return contacts updated since the date specified. (Date) (Default: "")