Contacts
The
contacts
object 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
Contact
objects. (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
ContactError
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
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
true
if thisContactField
contains 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_ERROR
ContactError.INVALID_ARGUMENT_ERROR
ContactError.NOT_FOUND_ERROR
ContactError.TIMEOUT_ERROR
ContactError.PENDING_OPERATION_ERROR
ContactError.IO_ERROR
ContactError.NOT_SUPPORTED_ERROR
ContactError.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: "")