Gestire i contatti della rubrica

È possibile gestire i contatti della rubrica di un dispositivo tramite l’oggetto globale contacts accessibile tramite il solito navigator. Dal punto di vista di Cordova, un contatto è un oggetto che ha le seguenti proprietà:

Da segnalare che le proprietà elencate sono quelle previste da Apache Cordova ma il loro effettivo supporto dipende dalla specifica piattaforma.

Tramite il metodo create() dell’oggetto contacts possiamo creare un nuovo contatto come mostrato dal seguente codice:

var myContact = navigator.contacts.create({"displayName": "Mario Rossi", "note": "Nuovo utente"});
myContact.name.givenName = "Mario";
myContact.name.familyName = "Rossi";
myContact.phoneNumbers.push({"type": "home", "value": "0123456789"});

I dettagli del nuovo contatto possono essere forniti direttamente al metodo create() o aggiunti all’oggetto restituito dal metodo. È importante notare che il metodo create() si limita a creare un oggetto di tipo contatto senza aggiungerlo alla rubrica, cosa che può essere fatta tramite il metodo save() del contatto stesso:

myContact.save(onSuccess, onError);

Gli argomenti specificati rappresentano le funzioni di callback da eseguire rispettivamente in caso di successo o di errore nel salvataggio del contatto. Sono previsti anche i metodi remove(), per eliminare un contatto dalla rubrica, e clone(), per creare una copia.

Possiamo interrogare la rubrica del dispositivo per trovare uno o più contatti sfruttando il metodo find() dell’oggetto contacts:

var options = new ContactFindOptions();
options.filter = "Rossi";
options.multiple = true;
var fields = ["displayName", "phoneNumbers"];
navigator.contacts.find(fields, onSuccess, onError, options);

Il metodo richiede un array di stringhe che rappresenta l’elenco dei campi del contatto da recuperare, le callback di successo ed errore ed un oggetto opzionale di tipo ContactFindOptions contenente i criteri di ricerca. Questo oggetto prevede due proprietà: filter, che consente di specificare una stringa per filtrare i contatti, e multiple, un valore booleano che indica se restituire tutti i contatti trovati (true) o soltanto il primo (false).

Il contatto o i contatti trovati vengono passati sotto forma di array di oggetti di tipo Contact alla callback di successo.