Contacts API
Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.
This API is available on Firefox OS for privileged or certified applications only.
Summary
The Contacts API provides a simple interface to manage a user's contacts stored in the system's address book. A typical use case for the Contacts API is the implementation of an application to manage an address book.
Note: Because personal information regarding a user's contact are pieces of sensitive data, only privileged and certified apps are allowed to directly access that API. Other applications are encouraged to use Web Activities to delegate operations on contacts.
Managing contacts
Contacts stored in the system's address book are accessible through the navigator.mozContacts
property, which is itself an instance of the ContactManager
interface.
Adding a contact
Creating a new entry in the system's address book is done in two steps:
- Instantiate a new
mozContact
object and fill in all necessary properties. ThemozContact
interface defines all possible properties for a given contact. Those properties are mostly the same as the ones defined in the vCard 4.0 specification, with the following exceptions:- The vCard N attribute is split into five properties:
familyName
,givenName
,additionalName
,honorificPrefix
,honorificSuffix
- The vCard FN attribute has been renamed
name
- The vCard GENDER attribute is split into two properties:
sex
,genderIdentity
- Be careful: most properties are arrays. Firefox v1.3 is much more strict in ensuring this and therefore some working code in Firefox v1.2 can stop working in Firefox v1.3 because of this.
- The vCard N attribute is split into five properties:
- Use the
ContactManager.save()
method with the contact object as its first parameter. The method returns aDOMRequest
to keep track of the save operation's success or error.
// first way: setting the properties directly var person = new mozContact(); person.givenName = ["John"]; person.familyName = ["Doe"]; person.nickname = ["No kidding"]; // second way: using a value object var contactData = { givenName: ["John"], familyName: ["Doe"], nickname: ["No kidding"] }; var person = new mozContact(contactData); // Firefox OS 1.3 takes a parameter to initialize the object if ("init" in person) { // Firefox OS 1.2 and below uses a "init" method to initialize the object person.init(contactData); } // save the new contact var saving = navigator.mozContacts.save(person); saving.onsuccess = function() { console.log('new contact saved'); // This update the person as it is stored // It includes its internal unique ID // Note that saving.result is null here }; saving.onerror = function(err) { console.error(err); };
Finding a contact
There are two methods to retrieve a contact from the system's address book:
ContactManager.find()
to retrieve a specific list of contactsContactManager.getAll()
to retrieve all the contacts
Both methods expect a parameter which is an object that defines the filter and sort options. ContactManager.getAll
only accepts the sort options. Those options are:
sortBy
: A string representing the field by which the results of the search are sorted. Currently only givenName and familyName are supported.sortOrder
: A string indicating the result's sort order. Possible values aredescending
orascending
.
And the filter options:
filterBy
: An array of strings representing all the fields to filter by.filterValue
: The value to match against.filterOp
: The filter comparison operator to use. Possible values areequals
,startsWith
, andmatch
, the latter being specific to telephone numbers.filterLimit
: The number of contacts to retrieve for thefind
method.
find
returns a DOMRequest
object and getAll
returns a DOMCursor
object to access the success or error of a search.
If the search is successful, the result of the search is available in the DOMRequest.result
property as either an Array of mozContact
objects for find
, or a single mozContact
object for getAll
. To receive the next result in the list with getAll
, call the cursor's continue()
method.
var options = { filterValue : "John", filterBy : ["givenName","name","nickName"], filterOp : "contains", filterLimit : 1, sortBy : "familyName", sortOrder : "ascending" } var search = navigator.mozContacts.find(options); search.onsuccess = function() { if (search.result.length === 1) { var person = search.result[0]; console.log("Found:" + person.givenName[0] + " " + person.familyName[0]); } else { console.log("Sorry, there is no such contact.") } }; search.onerror = function() { console.warn("Uh! Something goes wrong, no result found!"); }; var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"}); allContacts.onsuccess = function(event) { var cursor = event.target; if (cursor.result) { console.log("Found: " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]); cursor.continue(); } else { console.log("No more contacts"); } }; allContacts.onerror = function() { console.warn("Something went terribly wrong! :("); };
Updating a contact
When retrieving a contact through find()
or getAll()
(or after a successful call to save()
for a new contact), this contact has some metadata attached to it:
- A unique ID available via
mozContact.id
- A Date object within
mozContact.updated
representing the last time the contact was updated.
Updating the contact is just about changing its properties values, then saving it through a call to the save()
method.
Note: Each time a contact is added, updated, or deleted a contactchange
event is fired in order to keep track of any change on the system's address book. This event can be handled with the ContactManager.oncontactchange
property.
Deleting a contact
A call to the ContactManager.remove()
method will simply delete the mozContact
object that was passed in.
In some edge cases, it's also possible to get rid of all contacts. To do this, use ContactManager.clear()
. Be careful when calling that method; there is no way back.
Specifications
Specification | Status | Comment |
---|---|---|
Contacts Manager API The definition of 'Contacts Manager API' in that specification. |
Working Draft | |
vCard Format Specification | IETF RFC | RFC 6350 |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
basic support | No support | No support | No support | No support | No support |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|---|
basic support | No support | No support | 18.0 | 1.1 | No support | No support | No support |
See also
navigator.mozContacts
mozContact
ContactManager
MozContactChangeEvent
- Firefox OS Contact Exported Sample App
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/contacts_api