license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Contains properties that describe a contact, such as a user's personal or business contact.
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 by which to address the contact. (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. (ContactAddress[])
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 user-defined categories associated with the contact. (ContactField[])
urls: An array of web pages associated with the contact. (ContactField[])
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, otherwise executes an error callback with a ContactError
object.
save: Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.
The Contact
object represents a user's contact. Contacts can be created, stored, 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 contact fields listed above are supported on every device platform. Please check each platform's Quirks section for details.
function onSuccess(contact) { alert("Save Success"); }; function onError(contactError) { alert("Error = " + contactError.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(); name.givenName = "Jane"; name.familyName = "Doe"; contact.name = name; // save to device contact.save(onSuccess,onError);
// 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);
function onSuccess() { alert("Removal Success"); }; function onError(contactError) { alert("Error = " + contactError.code); }; // remove the contact from the device contact.remove(onSuccess,onError);
<!DOCTYPE html> <html> <head> <title>Contact Example</title> <script type="text/javascript" charset="utf-8" src="cordova.js"></script> <script type="text/javascript" charset="utf-8"> // Wait for device API libraries to load // document.addEventListener("deviceready", onDeviceReady, false); // device APIs are available // function onDeviceReady() { // create var contact = navigator.contacts.create(); contact.displayName = "Plumber"; contact.nickname = "Plumber"; // specify both to support all devices 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(contact) { 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> <h1>Example</h1> <p>Find Contacts</p> </body> </html>
null
.id: Supported. Assigned by the device when saving the contact.
displayName: Supported. Stored in BlackBerry user1 field.
nickname: Not supported, returning null
.
phoneNumbers: Partially supported. Phone numbers are 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 are stored in the BlackBerry email1, email2, and email3 fields, respectively.
addresses: Partially supported. The first and second addresses are stored in the BlackBerry homeAddress and workAddress fields, respectively.
ims: Not supported, returning 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 is 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.
displayName: Not supported on iOS, returning null
unless there is no ContactName
specified, in which case it returns the composite name, nickname or ""
, respectively.
birthday: Must be input as a JavaScript Date
object, the same way it is returned.
photos: Returns a File URL to the image, which is stored in the application's temporary directory. Contents of the temporary directory are removed when the application exits.
categories: This property is currently not supported, returning null
.
displayName: When creating a contact, the value provided for the display name parameter differs from the display name retrieved when finding the contact.
urls: When creating a contact, users can input and save more than one web address, but only one is available when searching the contact.
phoneNumbers: The pref option is not supported. The type is not supported in a find operation. Only one phoneNumber
is allowed for each type.
emails: The pref option is not supported. Home and personal references same email entry. Only one entry is allowed for each type.
addresses: Supports only work, and home/personal type. The home and personal type reference the same address entry. Only one entry is allowed for each type.
organizations: Only one is allowed, and does not support the pref, type, and department attributes.
note: Not supported, returning null
.
ims: Not supported, returning null
.
birthdays: Not supported, returning null
.
categories: Not supported, returning null
.