API Contacts

Non standard
Cette fonctionnalité n'est pas en voie de standardisation au W3C, mais elle est supportée par la plateforme Firefox OS. Bien que son implémentation puisse changer dans le futur et qu'elle n'est pas largement supportée par les différents navigateurs, elle est utilisable pour du code dédié aux applications Firefox OS.

Cette API est disponible sur Firefox OS pour des applications privilégiées ou certifiées seulement.

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.

Note : Comme les informations personnelles des contacts utilisateurs constituent des données sensibles, seules les applications certifiées et privilégiées sont autorisées à accéder à cette API. L'utilisation des Activités Web pour déléguer les opérations sur les contacts est préconisée pour les autres applications.

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 :

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 :

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

Note : À chaque fois qu'un contact est ajouté, mis à jour ou supprimé, un événement contactchange est déclenché afin d'avoir un suivi de tous les changements apportés au carnet d'adresses du système. Cet événement peut être géré avec la propriété ContactManager.oncontactchange.

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

Spécification État Commentaire
Contacts Manager API
La définition de 'Contacts Manager API' dans cette spécification.
Version de travail  
vCard Format Specification IETF RFC RFC 6350

Compatibilité des navigateurs

Caractéristique Chrome Firefox (Gecko) Internet Explorer Opera Safari
support basique Pas de support Pas de support Pas de support Pas de support Pas de support
Caractéristique Android Chrome pour Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
basic support Pas de support Pas de support 18.0 1.1 Pas de support Pas de support Pas de support

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : jwhitlock, xdelatour
 Dernière mise à jour par : jwhitlock,