Contacts
El objeto
contacts
proporciona acceso a la agenda del dispositivo.
Métodos
Argumentos
Objetos
contacts.create
Retorna un objeto Contact
nuevo.
var contact = navigator.contacts.create(properties);
Descripción
contacts.create es una función síncrona que retornara un objeto Contact
nuevo.
Este método no hace el contacto persistente en la base de datos de contactos. Para hacerlo persistente, llama al método Contact.save
.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
var myContact = navigator.contacts.create({"displayName": "Usuario Prueba"});
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() {
var myContact = navigator.contacts.create({"displayName": "Usuario Prueba"});
myContact.gender = "male";
console.log("El contacto, " + myContact.displayName + ", es de genero " + myContact.gender);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Creación de Contactos</p>
</body>
</html>
contacts.find
Consulta la base de datos de contactos y retorna uno o mas objetos Contact
, cada uno con los campos especificados.
navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);
Descripción
contacts.find es una función asíncrona que consulta la base de datos de la agenda del dispositivo y retorna un array de objetos Contact
. Los objetos retornados son pasados a la función 'callback' contactSuccess
especificada en el argumento contactSuccess.
Los usuarios pueden especificar los campos que solicitan en la consulta con el argumento contactFields. Solo los campos que solicites en contactFields serán retornados como propiedades del objeto Contact
, que a su vez es pasado a la función 'callback' contactSuccess. Si se entrega un array contactFields vacio, el objeto Contact
retornada solo las propiedades id
. El valor ["*"] en contactFields retornara todos los campos.
La string contactFindOptions.filter puede usarse como filtro cuando se consulte a la base de datos. Si se entrega, este valor es sensible a capitalización y a coincidencias parciales sobre cada campo que especificastes en el argumento contactFields. Si se encuentra una coincidencia con cualquier campo especificado, se retornara el contacto.
Argumentos
-
contactFields: Campos del contacto para usarse en las búsquedas. Solo estos campos tendrán valores asignados en el objeto
Contact
retornado. (DOMString[]) [Requerido] - contactSuccess: Función 'callback' Success que se dispara cuando se retorna un contacto de la base de datos. [Requerido]
- contactError: Función 'callback' Error. Se dispara cuando ocurre algún tipo de error. [Opcional]
- contactFindOptions: Opciones de búsqueda para filtrar contactos. [Opcional]
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
function onSuccess(contacts) {
alert('Se encontró ' + contacts.length + ' contactos.');
};
function onError(contactError) {
alert('onError!');
};
// Busca todos los contactos con 'Bob' en cualquier campo "name"
var options = new ContactFindOptions();
options.filter="Bob";
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
// Busca todos los contactos con 'Bob' en cualquier campo "name"
var options = new ContactFindOptions();
options.filter="Bob";
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado de los contactos actuales
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log("Nombre a mostrar (DisplayName) = " + contacts[i].displayName);
}
}
// onError: Fallo al obtener contactos
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
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
.
ContactAddress
Contiene propiedades de una de las direcciones de este contacto (Contact
).
Propiedades
-
pref:
true
si esteContactAddress
es preferido. (boolean) - type: Una string que te dice que tipo de dirección es esta (Ejemplo: 'Home'). _(DOMString)
- formatted: Toda la dirección formateada para mostrarla. (DOMString)
- streetAddress: La dirección de calle completa. (DOMString)
- locality: La ciudad o localidad. (DOMString)
- region: El estado o region. (DOMString)
- postalCode: Código postal o zip. (DOMString)
- country: Nombre del país. (DOMString)
Detalles
El objeto ContactAddress
almacena propiedades de un sola dirección del contacto. Un objeto Contact
puede tener una o mas direcciones en el array ContactAddress[]
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
// Muestra información sobre la dirección de todos los contactos
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].addresses.length; j++) {
alert("Preferente: " + contacts[i].addresses[j].pref + "\n" +
"Tipo: " + contacts[i].addresses[j].type + "\n" +
"Formateada: " + contacts[i].addresses[j].formatted + "\n" +
"Dirección: " + contacts[i].addresses[j].streetAddress + "\n" +
"Localidad: " + contacts[i].addresses[j].locality + "\n" +
"Provincia: " + contacts[i].addresses[j].region + "\n" +
"Código Postal: " + contacts[i].addresses[j].postalCode + "\n" +
"País: " + contacts[i].addresses[j].country);
}
}
};
function onError(contactError) {
alert('onError!');
};
// Busca todos los contactos
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
// Busca todos los contactos
var options = new ContactFindOptions();
options.filter="";
var filter = ["displayName","addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado
//
function onSuccess(contacts) {
// muestra la información de dirección de todos los contactos
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].addresses.length; j++) {
alert("Preferente: " + contacts[i].addresses[j].pref + "\n" +
"Tipo: " + contacts[i].addresses[j].type + "\n" +
"Formateada: " + contacts[i].addresses[j].formatted + "\n" +
"Dirección: " + contacts[i].addresses[j].streetAddress + "\n" +
"Localidad: " + contacts[i].addresses[j].locality + "\n" +
"Provincia: " + contacts[i].addresses[j].region + "\n" +
"Código Postal: " + contacts[i].addresses[j].postalCode + "\n" +
"País: " + contacts[i].addresses[j].country);
}
}
};
// onError: Ocurrió un error
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
Peculiaridades Android 2.X
-
pref: Esta propiedad no esta soportada por dispositivos Android 2.X, y siempre retornaran
false
.
Peculiaridades Android 1.X
-
pref: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
false
. -
type: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
. -
streetAddress: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
. -
locality: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
. -
region: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
. -
postalCode: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
. -
country: Esta propiedad no esta soportada por dispositivos Android 1.X, y siempre retornara
null
.
Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)
-
pref: Esta propiedad no esta soportada por dispositivos BlackBerry, y siempre retornara
false
. - type: Soportada parcialmente. Solo permite un "Work" y un "Home" por cada contacto.
- formatted: Soportada parcialmente. Retornara una concatenación de todos los campos de la dirección.
- streetAddress: Soportada. Retornara los campos concatenados address1 y address2.
- locality: Soportada. Almacenada en el campo city.
- region: Soportada. Almacenada en el campo stateProvince.
- postalCode: Soportada. Almacenada en el campo zipPostal.
- country: Soportada.
Peculiaridades iOS
-
pref: Esta propiedad no esta soportada por dispositivos iOS, y siempre retornara
false
. - formatted: Actualmente no esta soportado.
ContactField
Son campos genéricos de un objeto Contact
. Algunas de las propiedades que se almacenan como objetos ContactField
son: direcciones de email, números de teléfono, y urls.
Propiedades
- type: Una string que indica que tipo de campo es (ejemplo: 'home'). (DOMString)
- value: El valor del campo (Como un numero de teléfono o una dirección de email). (DOMString)
-
pref:
true
si este objetoContactField
es preferente. (boolean)
Detalles
El objeto ContactField
es un componente pensado para ser reusable. Cada objeto ContactField
contiene una propiedad value, una type y una pref. Los objetos Contact
almacenan varios objetos de este tipo en un array ContactField[]
, tales como números de teléfono o direcciones de emails.
En la mayoría de los casos no existen valores predeterminados para el atributo type. Por ejemplo, un numero de teléfono puede tener un valor type como 'home', 'work', 'mobile', 'iPhone' o cualquier otro, esto depende de la base de datos de la plataforma del dispositivo en cuestión. En cambio, en el caso del campo photos, PhoneGap hace uso del atributo type para indicar el formato de la imagen. PhoneGap retornara type: 'url' cuando cuando la propiedad value indique la URL al fichero de imagen, o type:'base64' cuando la imagen se retorne codificada como una string Base64.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
// crea un nuevo contacto
var contact = navigator.contacts.create();
// almacena números de teléfonos en ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // numero preferente
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// guarda el contacto
contact.save();
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
// crea un nuevo contacto
var contact = navigator.contacts.create();
// almacena números de teléfonos en ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // numero preferente
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// guarda el contacto
contact.save();
// busca contactos, obtiene el nombre a mostrar y los números de teléfono.
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","phoneNumbers"];
navigator.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
// display phone numbers
for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" +
"Value: " + contacts[i].phoneNumbers[j].value + "\n" +
"Preferred: " + contacts[i].phoneNumbers[j].pref);
}
}
};
// onError: Ocurrió un error
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
Peculiaridades Android
-
pref: Esta propiedad no esta soportada por dispositivos Android, y siempre retorna
false
.
Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)
- type: Soportada parcialmente. Usada para números de teléfonos.
- value: Soportada.
-
pref: Esta propiedad no esta soportada, y siempre retornara
false
.
Peculiaridades iOS
-
pref: Esta propiedad no esta soportada en iOS y siempre retornara
false
.
ContactFindOptions
Contiene propiedades que se usan para filtrar el resultado de contacts.find
.
Atributos
- filter: La cadena de texto que se usara para filtrar contactos. (DOMString) (Default: "")
- multiple: Indica si la operación de búsqueda debe retornar múltiples contactos. (Boolean) (Default: false)
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Sencillo
// Función 'callback' de una búsqueda satisfactoria
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert(contacts[i].displayName);
}
};
// retrollamada (callback) de una búsqueda errónea
function onError(contactError) {
alert('onError!');
};
// Indica criterios de búsqueda
var options = new ContactFindOptions();
options.filter=""; // una string vacía retorna todos los contactos
options.multiple=true; // retornar mas de un contacto
filter = ["displayName"]; // retornar el campo contact.displayName
// Busca contactos
navigator.contacts.find(filter, onSuccess, onError, options);
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
// Indica un criterio de búsqueda
var options = new ContactFindOptions();
options.filter=""; // una string vacía retorna todos los contactos
options.multiple=true; // retornar mas de un contacto
filter = ["displayName"]; // retornar el campo contact.displayName
// Busca contactos
navigator.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert(contacts[i].displayName);
}
};
// onError: Ocurrió un error
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
ContactName
Contiene atributos sobre nombres de un objeto Contact
.
Atributos
- formatted: El nombre completo del contacto formateado. (DOMString)
- familyName: Apellidos de familia. (DOMString)
- givenName: El primer nombre del contacto. (DOMString)
- middleName: El Segundo nombre del contacto, por ejemplo: de "Juan José" es "José". (DOMString)
- honorificPrefix: Prefijo del nombre, comúnmente por anglosajones (ejemplo: Mr, Dr...) (DOMString)
- honorificSuffix: Sufijo del nombre, comúnmente usado por anglosajones (ejemplo: Jr...). (DOMString)
Detalles
El objeto ContactName
guarda atributos sobre el nombre de un contacto.
Plataformas Soportadas
- Android 2.X
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert("Nombre formateado: " + contacts[i].name.formatted + "\n" +
"Apellidos: " + contacts[i].name.familyName + "\n" +
"Primer Nombre: " + contacts[i].name.givenName + "\n" +
"Segundo Name: " + contacts[i].name.middleName + "\n" +
"Sufijo del nombre: " + contacts[i].name.honorificSuffix + "\n" +
"Prefijo del nombre: " + contacts[i].name.honorificSuffix);
}
};
function onError(contactError) {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.contacts.find(filter, onSuccess, onError, options);
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
alert("Nombre formateado: " + contacts[i].name.formatted + "\n" +
"Apellidos: " + contacts[i].name.familyName + "\n" +
"Primer Nombre: " + contacts[i].name.givenName + "\n" +
"Segundo nombre: " + contacts[i].name.middleName + "\n" +
"Sufijo del nombre: " + contacts[i].name.honorificSuffix + "\n" +
"Prefijo del nombre: " + contacts[i].name.honorificPrefix);
}
};
// onError: Ocurrió un error
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
Peculiaridades Android
- formatted: Soportada parcialmente. Retornara la concatenación de honorificPrefix, givenName, middleName, familyName and honorificSuffix pero no sera almacenado.
Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)
- formatted: Soportada parcialmente. Retornara la concatenación de los campos de BlackBerryfirstName y lastName.
- familyName: Soportada. Almacenado en el campo de BlackBerry lastName.
- givenName: Soportada. Almacenada en el campo de BlackBerry firstName.
-
middleName: Esta propiedad no esta soportada, y siempre retornara
null
. -
honorificPrefix: Esta propiedad no esta soportada, y siempre retornara
null
. -
honorificSuffix: Esta propiedad no esta soportada, y siempre retornara
null
.
Peculiaridades iOS
- formatted: Soportada parcialmente. Retornara el nombre compuesto en iOS pero no lo almacenara.
ContactOrganization
Contiene atributos sobre la organización de un objeto Contact
.
Atributos
-
pref:
true
si esteContactOrganization
es la preferente del usuario. (boolean) - type: Una string que indica que tipo de campo es (ejemplo: 'home'). _(DOMString)
- name: El nombre de la organización. (DOMString)
- department: El departamento de la organización a donde el usuario pertenece. (DOMString)
- title: El titulo del usuario en su organización. (DOMString)
Detalles
El objeto ContactOrganization
almacena atributos sobre la organización. Un objeto Contact
guarda uno o mas objetos ContactOrganization
en un array.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].organizations.length; j++) {
alert("Preferente: " + contacts[i].organizations[j].pref + "\n" +
"Tipo: " + contacts[i].organizations[j].type + "\n" +
"Nombre: " + contacts[i].organizations[j].name + "\n" +
"Departmento: " + contacts[i].organizations[j].department + "\n" +
"Titulo: " + contacts[i].organizations[j].title);
}
}
};
function onError(contactError) {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);
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">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);
}
// onSuccess: Obtiene el resultado
//
function onSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
for (var j=0; j<contacts[i].organizations.length; j++) {
alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
"Type: " + contacts[i].organizations[j].type + "\n" +
"Name: " + contacts[i].organizations[j].name + "\n" +
"Department: " + contacts[i].organizations[j].department + "\n" +
"Title: " + contacts[i].organizations[j].title);
}
}
};
// onError: Ocurrió un error
//
function onError(contactError) {
alert('onError!');
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Búsqueda de Contactos</p>
</body>
</html>
Peculiaridades Android 2.X
-
pref: Este atributo no esta soportado en Android 2.X y siempre retornara
false
.
Peculiaridades Android 1.X
-
pref: Este atributo no esta soportado en Android 1.X y siempre retornara
false
. -
type: Este atributo no esta soportado en Android 1.X y siempre retornara
null
. -
title: Este atributo no esta soportado en Android 1.X y siempre retornara
null
.
Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)
-
pref: Este atributo no esta soportado en Blackberry y siempre retornara
false
. -
type: Este atributo no esta soportado en Blackberry y siempre retornara
null
. - name: Soportado parcialmente. El primer nombre de la organización se almacenara en el campo BlackBerry company.
-
department: Este atributo no esta soportado y siempre retornara
null
. - title: Soportado parcialmente. El primer titulo se almacenara en el campo BlackBerry jobTitle.
Peculiaridades iOS
-
pref: Este atributo no esta soportado en iOS y siempre retornara
false
. -
type: Este atributo no esta soportado en iOS y siempre retornara
null
. - name: Soportado parcialmente. El primer nombre de la organización sera almacenado en el campo iOS kABPersonOrganizationProperty.
- department: Soportado parcialmente. El primer nombre del departamento sera almacenado en el campo iOS kABPersonDepartmentProperty.
- title: Soportado parcialmente. El primer titulo sera almacenado en el campo iOS kABPersonJobTitleProperty.
ContactError
Cuando un error ocurra, se pasara un objeto ContactError
a la funcion 'callback' contactError
.
Propiedades
- code: Uno de los errores definidos en la lista inferior.
Constantes
ContactError.UNKNOWN_ERROR
ContactError.INVALID_ARGUMENT_ERROR
ContactError.TIMEOUT_ERROR
ContactError.PENDING_OPERATION_ERROR
ContactError.IO_ERROR
ContactError.NOT_SUPPORTED_ERROR
ContactError.PERMISSION_DENIED_ERROR
Descripción
Cuando ocurra un error, se disparara la funcion 'callback' ContactError
pasándole como argumento un objeto contactError
.
contactSuccess
Función 'callback' que proporciona un array de objetos Contact
como resultado del método contacts.find
.
function(contacts) {
// hacer algo
}
Argumentos
-
contacts: El array de contactos que retorna el método
contact.find
. (Contact
)
Ejemplo
function contactSuccess(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log("Nombre = " + contacts[i].displayName;
}
contactError
Función 'callback' de error para las funciones de contactos.
function(error) {
// Maneja el error
}
contactFields
Argumento requerido para el método contacts.find
. Úsalo para indicar que campos deberían incluirse en el objeto Contact
que este método retorna.
["name", "phoneNumbers", "emails"]
contactFindOptions
Argumento opcional del método contacts.find
. Usa este argumento para filtrar los contactos retornados de la base de datos de contactos.
{
filter: "",
multiple: true,
};
Opciones
- filter: Esta string de búsqueda se usara para filtrar contactos. (DOMString) (Por defecto: "")
- multiple: Indica si se debe retornar múltiples contactos. (Boolean) (Por defecto: false)