Storage
Proporciona acceso a las opciones de almacenamiento del dispositivo.
Esta API esta basada en la W3C Web SQL Database Specification y W3C Web Storage API Specification. Algunos dispositivos ya incluyen una implementación de estas especificaciones, en estos dispositivos, se usara la implementación incluida en vez de la implementación PhoneGap. Para los dispositivos que no incluyan de serie soporte de la API de almacenamiento, la implementación PhoneGap debe ser compatible con las especificaciones de la W3C.
Métodos
Argumentos
Objetos
openDatabase
Retorna un nuevo objeto Database
.
var dbShell = window.openDatabase(name, version, display_name, size);
Descripción
window.openDatabase
retorna un nuevo objeto Database
.
Este método creara una nueva pequeña base de datos SQL y retorna un objeto Database
. Usa este objeto Database
para manipular los datos.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido
var db = window.openDatabase("prueba", "1.0", "Prueba DB", 1000000);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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 db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 1000000);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Abriendo Base de Datos</p>
</body>
</html>
name
El nombre de la base de datos.
version
La versión de la base de datos.
display_name
El nombre a mostrar de la base de datos.
size
El tamaño de la base de datos en bytes.
Database
Contiene métodos que permiten al usuario manipular la base de datos.
Métodos
- transaction: Ejecuta una transacción en la base de datos.
- changeVersion: Permite a los scripts comprobar atómicamente el numero de versión y cambiarlo a la vez que actualiza el esquema.
Detalles
Un objeto Database
es retornado de la llamada window.openDatabase()
.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido de Transaction
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
function errorCB(err) {
alert("Error procesando SQL: "+err.code);
}
function successCB() {
alert("Correcto!");
}
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
Ejemplo Rápido de Cambio de Versión
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.changeVersion("1.0", "1.1");
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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 db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
}
// Rellena la base de datos
//
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
// Función 'callback' de error de transacción
//
function errorCB(tx, err) {
alert("Error procesando SQL: "+err);
}
// Función 'callback' de transacción satisfactoria
//
function successCB() {
alert("bien!");
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Base de datos</p>
</body>
</html>
Peculiaridades Android 1.X
- changeVersion: Este método no esta soportado por los dispositivos Android 1.X.
SQLTransaction
Este objeto tiene métodos que permiten al usuario ejecutar sentencias SQL en la base de datos.
Métodos
- executeSql: Ejecuta una sentencia SQL
Detalles ----.---
Cuando uses el método Database.transaction
, se le pasara un objeto SQLTransaction
a su función callback, cuando hagas una transacción puedes usar el método executeSql varias veces.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido de executeSql
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
function errorCB(err) {
alert("Error procesando SQL: "+err);
}
function successCB() {
alert("Correcto!");
}
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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 db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
}
// Rellena la base de datos
//
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
// Función 'callback' de error de transacción
//
function errorCB(err) {
alert("Error procesando SQL: "+err);
}
// Función 'callback' de transacción correcta
//
function successCB() {
alert("success!");
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>SQLTransaction</p>
</body>
</html>
SQLResultSet
Cuando se ejecuta el método SQLTransaction.executeSql
se llamara a esta función 'callback' pasándole el resultado de la consulta.
Atributos
-
insertId: El ID de la fila que el objeto
SQLResultSet
inserto en la base de datos. - rowAffected: El numero de filas que cambiaron por la sentencia SQL. Si la sentencia no afecto a ninguna fila se retornara 0.
-
rows: Un objeto
SQLResultSetRowList
representando la fila retornada. Si no se retorno ninguna, este objeto estará vacio.
Detalles
Cuando llamas al método SQLTransaction.executeSql
, esta función sera llamada pasándole un objeto SQLResultSet. Este objeto tendrá tres atributos, el primero (insertId
) retornara el numero de fila de una sentencia 'insert' satisfactoria. Si la sentencia SQL no fuera una sentencia 'insert', este atributo no sera establecido. El atributo rowAffected
es siempre 0 para una sentencia SQL de tipo 'select'. Para sentencias 'insert' o 'update' retornara el numero de filas que fueron afectadas. El ultimo atributo es de tipo SQLResultSetList
y contiene los datos retornados por una sentencia SQL de tipo 'select'.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
function querySuccess(tx, results) {
// debería estar vacio ya que se inserto nada
console.log("ID insert = " + results.insertId);
// Sera 0 debido que es una sentencia SQL de tipo 'select'
console.log("Filas afectadas = " + results.rowAffected);
// El numero de filas retornadas
console.log("Filas retornadas = " + results.rows.length);
}
function errorCB(err) {
alert("Error procesando SQL: "+err.code);
}
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(queryDB, errorCB);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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);
// Componemos la base de datos
//
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
// Consultamos la base de datos
//
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
// Función 'callback' con el resultado de la consulta
//
function querySuccess(tx, results) {
// debería estar vacio ya que se inserto nada
console.log("ID insert = " + results.insertId);
// Sera 0 debido que es una sentencia SQL de tipo 'select'
console.log("Filas afectadas = " + results.rowAffected);
// El numero de filas retornadas
console.log("Filas retornadas = " + results.rows.length);
}
// Función 'callback' de error
//
function errorCB(err) {
console.log("Error procesando SQL: "+err.code);
}
// Función 'callback' de transacción satisfactoria
//
function successCB() {
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(queryDB, errorCB);
}
// PhoneGap esta lista
//
function onDeviceReady() {
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Database</p>
</body>
</html>
SQLResultSetList
Uno de los atributos de SQLResultSet
, contiene las filas retornadas por la consulta SQL.
Atributos
- length: El numero de filas retornadas por la consulta SQL
Métodos
- item: Retorna las filas con el índice especificado, representado por un objeto JavaScript.
Detalles
SQLResultSetList
contiene los datos retornados por la sentencia SQL 'select'. Este objeto contiene un atributo length
mostrándote cuantas filas fueron retornadas por la sentencia 'select'. Para obtener una de las filas, deberás llamar al método item
especificando el índice de la fila. El método item retorna un objeto JavaScript donde los atributos son las columnas de la sentencia SQL ejecutada.
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido de executeSql
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
function querySuccess(tx, results) {
var len = results.rows.length;
console.log("Tabla DEMO: " + len + " filas encontradas.");
for (var i=0; i<len; i++){
console.log("Fila = " + i + " ID = " + results.rows.item(i).id + " Datos = " + results.rows.item(i).data);
}
}
function errorCB(err) {
alert("Error procesando SQL: "+err.code);
}
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(queryDB, errorCB);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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);
// Rellena la base de datos
//
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS DEMO');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "Primera fila")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Segunda fila")');
}
// Consulta a la base de datos
//
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
// Función 'callback' con el resultado de la consulta
//
function querySuccess(tx, results) {
var len = results.rows.length;
console.log("Tabla DEMO: " + len + " filas encontradas.");
for (var i=0; i<len; i++){
console.log("Fila = " + i + " ID = " + results.rows.item(i).id + " Datos = " + results.rows.item(i).data);
}
}
// Función 'callback' de error de transacción
//
function errorCB(err) {
console.log("Error procesando SQL: "+err.code);
}
// Función 'callback' de transacción correcta
//
function successCB() {
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(queryDB, errorCB);
}
// PhoneGap esta listo
//
function onDeviceReady() {
var db = window.openDatabase("Database", "1.0", "Demo PhoneGap", 200000);
db.transaction(populateDB, errorCB, successCB);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Database</p>
</body>
</html>
SQLError
Se lanza un objeto SQLError
cada vez que ocurre un error.
Atributos
- code: Uno de los códigos de error predefinidos en la lista inferior.
- message: Una descripción del error.
Constantes
SQLError.UNKNOWN_ERR
SQLError.DATABASE_ERR
SQLError.VERSION_ERR
SQLError.TOO_LARGE_ERR
SQLError.QUOTA_ERR
SQLError.SYNTAX_ERR
SQLError.CONSTRAINT_ERR
SQLError.TIMEOUT_ERR
Descripción
El objeto SQLError
es lanzado cuando ocurre un error mientras se manipula la base de datos.
localStorage
Proporciona acceso a la interfaz W3C Storage (http://dev.w3.org/html5/webstorage/#the-localstorage-attribute)
var storage = window.localStorage;
Métodos
- key: Retorna el nombre de la llave en la posición especificada.
- getItem: Retorna el valor de la llave especificada.
- setItem: Guarda un valor para esta llave.
- removeItem: Elimina el registro de la llave especificada.
- clear: Elimina todos los registros (valores y llaves).
Detalles
localStorage proporciona una interfaz a la API W3C Storage. Esta API permite guardar datos tipo diccionario (llave-valor).
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 6.0 y superior)
- iPhone
Ejemplo Rápido de key
var keyName = window.localStorage.key(0);
Ejemplo Rápido de setItem
window.localStorage.setItem("key", "value");
Ejemplo Rápido de getItem
var value = window.localStorage.getItem("key");
// Ahora la variable value es "value"
Ejemplo Rápido de removeItem
window.localStorage.removeItem("key");
Ejemplo Rápido de clear
window.localStorage.clear();
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Storage</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() {
window.localStorage.setItem("llave", "valor");
var keyname = window.localStorage.key(i);
// keyname ahora es "llave"
var value = window.localStorage.getItem("llave");
// value ahora es "valor"
window.localStorage.removeItem("llave");
window.localStorage.setItem("llave2", "valor2");
window.localStorage.clear();
// localStorage esta ahora vacio
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>localStorage</p>
</body>
</html>