È 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.
16 / 19

Gestire accelerometro e bussola