Contact

Contiene propiedades que describen un contacto, como su información personal o de trabajo.

Atributos

id: Un identificador unico y global. (DOMString)
displayName: El nombre de este contacto. Ideal para mostrar al usuario final. (DOMString)
name: Un objeto conteniendo todos las partes del nombre de una persona. (ContactName)
nickname: Un apodo por el que conoces a la persona. (DOMString)
phoneNumbers: Un array de todos sus números de teléfono. (ContactField[])
emails: Un array de todas sus direcciones de email. (ContactField[])
addresses: Un array de todas sus direcciones de contacto. (ContactAddresses[])
ims: Un array de todas las direcciones de mensajeria instantanea. (ContactField[])
organizations: Un array con todos sus nombres de organizaciones. (ContactOrganization[])
birthday: La fecha de nacimiento del contacto. (Date)
note: Una nota sobre este contacto. (DOMString)
photos: Un array de fotos del contacto. (ContactField[])
categories: Un array de todas las categorías del contacto. (ContactField[])
urls: Un array de sitios webs asociados a este contacto. (ContactField[])

Metodos

clone: Retorna un nuevo objeto del contacto, es una copia de este contacto con la propiedad ID null.
remove: Elimina el contacto de la base de datos del dispositivo. Se disparara una función ‘callback’ de error si no se pudo eliminar.
save: Guarda el contacto en la base de datos, o actualiza el contacto si ya existe un contacto con la misma id.

Detalles

El objeto Contact representa un contacto. Los contactos pueden ser creados, guardados o eliminados de la base de datos del dispositivo. También pueden ser retornados (Individualmente o en masa) llamando al método contacts.find.

Nota: No todos los campos de contactos están soportados en todas las plataformas. Comprueba las peculiaridades de cada plataforma para saber que campos están soportados.

Plataformas Soportadas

Android
BlackBerry WebWorks (OS 5.0 y superior)
iOS

Ejemplo Rápido de Guardado

function onSuccess(contact) {
	alert("Se guardo satisfactoriamente");
};

function onError(contactError) {
	alert("Error = " + contactError.code);
};

// crea un nuevo objeto contacto
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber"; 		// especifica ambos para soportar todos los dispositivos

// Rellena varios campos
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// guarda en el dispositivo
contact.save(onSuccess,onError);

Ejemplo Rápido de Clonación

// Clona el objeto contacto
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Nombre del contacto original = " + contact.name.givenName);
console.log("Nombre del contacto clonado = " + clone.name.givenName);

Ejemplo Rápido de eliminación

function onSuccess() {
    alert("Se elimino satisfactoriamente");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// elimina el contacto del dispositivo
contact.remove(onSuccess,onError);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espere a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
	    // crea
	    var contact = navigator.contacts.create();
		contact.displayName = "Plumber";
		contact.nickname = "Plumber"; 		//especifica ambos para soportar todos los dispositivos
		var name = new ContactName();
		name.givenName = "Jane";
		name.familyName = "Doe";
		contact.name = name;

		// guarda
		contact.save(onSaveSuccess,onSaveError);
		
		// clona
		var clone = contact.clone();
		clone.name.givenName = "John";
		console.log("Nombre del contacto original = " + contact.name.givenName);
		console.log("Nombre del contacto clonado = " + clone.name.givenName); 
		
		// elimina
		contact.remove(onRemoveSuccess,onRemoveError);
    }
    
    // onSaveSuccess: Obtiene el contacto guardado satisfactoriamente
    //
    function onSaveSuccess(contact) {
		alert("Se guardo satisfactoriamente");
    }

    // onSaveError: Fallo al guardar el contacto
    //
    function onSaveError(contactError) {
		alert("Error = " + contactError.code);
    }
    
    // onRemoveSuccess: Obtiene el contacto eliminado satisfactoriamente
    //
    function onRemoveSuccess(contacts) {
		alert("Eliminado satisfactoriamente");
    }

    // onRemoveError: Fallo al eliminar el contacto
    //
    function onRemoveError(contactError) {
		alert("Error = " + contactError.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android 2.X

categories: Esta propiedad no esta soportada por dispositivos Android 2.X, y siempre retornara null.

Peculiaridades Android 1.X

name: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.
nickname: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.
birthday: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.
photos: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.
categories: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.
urls: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara null.

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

id: Soportada. Asignada por el dispositivo cuando un contacto es guardado.
displayName: Soportada. Almacenada en el campo user1.
nickname: Esta propiedad no esta soportada, y siempre retornara null.
phoneNumbers: Soportada parcialmente. Los números de teléfonos seran almacenados en los campos homePhone1 y homePhone2 si el type es ‘home’, workPhone1 y workPhone2 si el type es ‘work’, mobilePhone si el type es ‘mobile’, faxPhone si el type es ‘fax’, pagerPhone si el type es ‘pager’, y otherPhone si el type no es ninguno de los anteriores.
emails: Soportada parcialmente. Los primeros tres direcciones de emails serán almacenadas en los campos email1, email2, y email3 respectivamente.
addresses: Soportada parcialmente. La primera y la segunda dirección serán almacenadas en los campos homeAddress y workAddress respectivamente.
ims: Esta propiedad no esta soportada, y siempre retornara null.
organizations: Soportada parcialmente. el campo name y title de la primera organización serán almacenadas en los campos company y title respectivamente.
photos: Soportada Parcialmente. Solo se permite una miniatura de foto. Para poner una imagen del contacto pásala codificada en Base64, o la ruta URL que apunta a la imagen. La imagen sera dimensionada antes de guardarla en la base de datos de BlackBerry. La foto de contacto sera retornada como Base64.
categories: Soportada parcialmente. Solo están soportadas las categorías ‘Business’ y ‘Personal’.
urls: Soportada parcialmente. Solo la primera URL se almacenara en el campo webpage.

Peculiaridades iOS

displayName: Esta propiedad no esta soportada por iOS y siempre retornara null a menos que no halla un ContactName especificado. Si no hay ningún ContactName, entonces respectivamente el nombre compuesto, el nickame o "" como valor de displayName.
birthday: Cuando introduzcas esta propiedad, esta debe ser dada como un objeto Date de JavaScript. También se retorna como un objeto Date de JavaScript.
photos: La foto se guarda en el directorio temporal de aplicaciones, y retorna una URL hacia esta. El contenido de este directorio temporal se eliminara cuando la aplicacion termine.
categories: Esta propiedad no esta soportada, y siempre retornara null.