È 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à:
| Proprietà | Descrizione |
|---|---|
| id | Un identificatore univoco del contatto |
| displayName | Il nome del contatto adatto alla visualizzare per l'utente |
| name | Il nome del contatto in tutte le sue componenti: nome, cognome, secondo nome, prefisso, ecc. Questa proprietà è a sua volta un oggetto. |
| nickname | Il nickname del contatto |
| phoneNumbers | Un array di oggetti che rappresentano i recapiti telefonici del contatto |
| emails | Un array di oggetti che rappresentano i recapiti di posta elettronica del contatto |
| addresses | Un array di oggetti che rappresentano i recapiti postali del contatto |
| ims | Un array di oggetti che rappresentano i recapiti di messaggistica istantanea del contatto |
| organizations | Un array di oggetti che rappresentano le organizzazioni di appartenenza del contatto |
| birthday | La data di compleanno del contatto |
| note | Note sul contatto |
| photos | Un array di oggetti che rappresentano foto del contatto |
| categories | Un array di oggetti che rappresentano delle categorie assegnate dall'utente al contatto |
| urls | Un array di oggetti che rappresentano pagine web associate al contatto |
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.
