ContactField
Supports generic fields in a [Contact](../Contact/contact.html)
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)
- pref: 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 pref property. A [Contact](../Contact/contact.html)
object stores several properties in ContactField[]
arrays, such as phone numbers and email addresses.
In most instances, there are no pre-determined values for the type attribute of a ContactField
object. For example, a phone number can have type values of 'home', 'work', 'mobile', 'iPhone', or any other value that is supported by the contact database on a particular device platform. However, in the case of the [Contact](../Contact/contact.html)
photos field, Cordova makes use of the type field to indicate the format of the returned image. Cordova will return type: 'url' when the value attribute contains a URL to the photo image, or type: 'base64' when the returned value attribute contains a Base64 encoded image string.
Supported Platforms
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
- Bada 1.2 & 2.0
- Windows Phone 7 and 8
- Windows 8
Quick Example
// create a new contact
var contact = navigator.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// save the contact
contact.save();
Full Example
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="cordova-2.5.0.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 a new contact
var contact = navigator.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred 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](../ContactFindOptions/contactfindoptions.html)();
options.filter="";
filter = ["displayName","phoneNumbers"];
navigator.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++) {
// display phone numbers
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" +
"Preferred: " + contacts[i].phoneNumbers[j].pref);
}
}
};
// onError: Failed to get the contacts
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
Android Quirks
- pref: This property is not support by Android devices, and will always return
false
.
BlackBerry WebWorks (OS 5.0 and higher) Quirks
- type: Partially supported. Used for phone numbers.
- value: Supported.
- pref: This property is not supported, and will always return
false
.
iOS Quirks
- pref: This property is not supported on iOS devices and will always return
false
.
Bada Quirks
- type: Property has to be one of the following for Email or Address fields: "WORK", "HOME". Property has to be one of the following for Phone fields: "WORK", "HOME", "VOICE", "FAX", "MSG", "CELL", "PAGER","BBS", "MODEM", "CAR", "ISDN","VIDEO", "PCS"