API Contacts

Résumé

L'API Contacts fournit une interface simple pour gérer les contacts des utilisateurs enregistrés dans le carnet d'adresses du système. Un cas pratique typique de l'API Contacts est l'implémentation d'une application de gestion de carnet d'adresses.

Gestion des contacts

Les contacts enregistrés dans le carnet d'adresses du système sont accessibles par l'intermédiaire de la propriété navigator.mozContacts, elle-même étant une instance de l'interface ContactManager.

Ajout d'un contact

La création d'une nouvelle entrée dans le carnet d'adresses du système se fait en deux étapes :

1. Instanciez un nouvel objet mozContact et remplissez toutes les propriétés nécéssaires. L'interface mozContact définit toutes les propriétés possibles pour un contact donné. Ces propriétés sont essentiellement les mêmes que celles définies dans la spécification vCard 4.0, avec les exceptions suivantes :
   • L'attribut vCard N est divisé en cinq propriétés : familyName, givenName, additionalName, honorificPrefix, honorificSuffix
   • L'attribut vCard FN a été renommé name
   • L'attribut vCard GENDER est divisé en deux propriétés : sex, genderIdentity
   • Faîtes attention : la plupart des propriétés sont des tableaux. Firefox v1.3 vérifie cela de manière bien plus stricte et par conséquent du code qui fonctionnait avec Firefox v1.2 peut ne plus s'exécuter avec Firefox v1.3 à cause de ça.
2. Utilisez la méthode ContactManager.save() avec l'objet contact comme premier paramètre. La méthode renvoie un DOMRequest pour conserver une trace de la réussite ou de l'échec de l'opération d'enregistrement.

// première méthode : définir les propriétés directement
var person = new mozContact();
person.givenName  = ["John"];
person.familyName = ["Doe"];
person.nickname   = ["No kidding"];

// seconde méthode : utilisation d'un objet
var contactData = {
  givenName: ["John"],
  familyName: ["Doe"],
  nickname: ["No kidding"]
};

var person = new mozContact(contactData); // Firefox OS 1.3 prend un paramètre pour initialiser l'objet
if ("init" in person) {
  // Firefox OS 1.2 et précédents utilisent une méthode "init" pour initialiser l'objet
  person.init(contactData);
}

// enregistre le nouveau contact
var saving = navigator.mozContacts.save(person);

saving.onsuccess = function() {
  console.log('nouveau contact enregistré');
  // Cela actualise la personne telle qu'elle est enregistrée
  // Elle comporte son ID interne unique
  // Notez que saving.result est null ici
};

saving.onerror = function(err) {
  console.error(err);
};

Recherche d'un contact

Deux méthodes permettent de récupérer un contact depuis le carnet d'adresses du système :

• ContactManager.find() pour obtenir une liste de contacts spécifique
• ContactManager.getAll() pour récupérer tous les contacts

Les deux méthodes attendent un paramètre qui est un objet défiinissant les options de filtres et de tri. ContactManager.getAll n'accepte que les options de tri. Ces dernières sont :

• sortBy : Une chaîne de caractères représentant le champ sur lequel les résultats de la recherche seront triés. Pour le moment, seuls givenName et familyName sont supportés.
• sortOrder : Une chaîne de caractères qui indique le sens du tri des résultats. Les valeurs possibles sont descending (descendant) ou ascending (ascendant).

Et les options de filtre :

• filterBy : Un tableau de chaînes de caractères représentant tous les champs utilisés pour le filtrage.
• filterValue : La valeur avec laquelle faire la comparaison.
• filterOp : L'opérateur de comparaison du filtre à utiliser. Les valeurs possibles sont equals (égal à), startsWith (commence par), et match (correspond à), cette dernière étant spécifique aux numéros de téléphone.
• filterLimit : Le nombre de contacts à récupérer avec la méthode find.

find renvoie un objet DOMRequest et getAll retourne un objet DOMCursor pour connaître la réussite ou l'échec d'une recherche.

Si la recherche réussit, son résultat est disponible dans la propriété DOMRequest.result, soit dans un tableau d'objets mozContact pour find, soit dans un unique objet mozContact pour getAll. Pour obtenir le résultat suivant dans la liste obtenue avec getAll, appelez la méthode continue() du curseur.

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("Trouvé :" + person.givenName[0] + " " + person.familyName[0]);
  } else {
    console.log("Désolé, il n'y a pas de tel contact.")
  }
};

search.onerror = function() {
  console.warn("Aïe ! Quelque chose ne va pas, aucun résultat !");
};

var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});

allContacts.onsuccess = function(event) {
  var cursor = event.target;
  if (cursor.result) {
    console.log("Trouvé : " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
    cursor.continue();
  } else {
    console.log("Pas d'autre contact");
  }
};

allContacts.onerror = function() {
  console.warn("Quelque chose s'est mal passée ! :(");
};

Mise à jour d'un contact

Lors de l'obtention d'un contact par l'intermédiaire de find() ou de getAll() (ou après un appel réussi à save() pour un nouveau contact), celui-ci se voit attribuer des méta-données :

• Un ID unique accessible via mozContact.id
• Un objet Date à l'intérieur de mozContact.updated pour représenter la date de dernière modification du contact.

Actualiser un contact revient globalement à modifier les valeurs de ses propriétés puis à l'enregistrer via un appel à la méthode save().

Suppression d'un contact

Un appel à la méthode ContactManager.remove() va tout simplement supprimer l'objet mozContact qui lui a été transmis.

Dans certains cas limites, il est aussi possible de se débarrasser de tous les contacts. Pour cela, utilisez ContactManager.clear(). Soyez prudent lors de l'appel de cette méthode ; il n'est pas possible de revenir en arrière.

Spécifications

Compatibilité des navigateurs

Voir aussi

• navigator.mozContacts
• mozContact
• ContactManager
• MozContactChangeEvent
• Application d'exemple pour exporter les contacts sous Firefox OS