HTML5 Database

This object provides functions to manipulate client-side databases using SQL.


Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
window.openDatabase Y Y Y Y Y YY
changeVersion Y Y Y Y Y YY
readTransaction Y Y Y Y Y YY
transaction Y Y Y Y Y YY
version Y Y Y Y Y YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Functions


Properties

String version

Constructors

window.openDatabase (name : String, version : String, displayName : String, estimatedSize : Number, creationCallback : function)


Creates a new database object. If the database already exists, the existing database will be returned and the creation callback will not be invoked.

Note: A SD card is the required method of storage for databases for 5.x devices


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
name The name of the database to be created
version The version of the database to be created
displayName The display name of the database to be created
estimatedSize The estimated size in bytes of the database
creationCallback The callback will be invoked when the database is first created.

database: The newly created database

Code Example:
Database db = window.openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024);
/**

//Create a namespace to hold our database variable
if (typeof mynamespace === 'undefined') {
    mynamespace = {};
}

(function () {

    //This method is only called once (the first time the database is created)
    function onDBCreate(database) {
        //Attach the database because "window.openDatabase" would not have returned it
        mynamespace.db = database;
        database.transaction(
            function (tx) {tx.executeSql('CREATE TABLE tbl_name (key int unique, name text)',
                [],
                function (tx, res) {
                    alert("Table Created Successfully");
                },
                function (tx, err) {
                    alert("ERROR - Table creation failed - code: " + err.code + ", message: " + err.message);
                });
            }
        );
    }

    if (window.openDatabase) {
        //Will either return the existing database or null and call our creation callback onDBCreate
        mynamespace.db = window.openDatabase('awesome', '1.0', 'The most awesome database ever', 5 * 1024 * 1024, onDBCreate);
    } else {
        alert("This device does not have HTML5 Database support");
    }
}());

Functions

void changeVersion (oldVersion : String, newVersion : String, callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])


This method allows scripts to atomically verify the version number and change it at the same time as doing a schema update. When the method is invoked, it immediately returns, and then asynchronously runs the transaction steps with the transaction callback being the third argument, the error callback being the fourth argument, the success callback being the fifth argument. If any of the optional arguments are omitted, then they are treated as if they were null.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
oldVersion database's current version.
newVersion database's new version.
callback Function to be called when executing SQL statements.

transaction: The transaction to be executed.
errorCallback Function to be called when an SQL error occurs.

error: The SQLError object describing the SQL error that occurred.
successCallback Function to be called when SQL statement is executed successfully.

Code Example:
db.changeVersion('', '1.0', function (t) {...});

void readTransaction (callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])


When called, this method immediately returns and then asynchronously runs the transaction steps with the transaction callback being the first argument, the error callback being the second argument, if any, the success callback being the third argument, if any, and with no preflight operation or postflight operation. The mode is read-only.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
callback Function to be called when executing SQL statements.

transaction: The transaction to be executed.
errorCallback Function to be called when an SQL error occurs.

error: The SQLError object describing the SQL error that occurred.
successCallback Function to be called when SQL statement is executed successfully.

Code Example:
function showDocCount(db, span) {
	db.readTransaction(
		function (t) {
			t.executeSql('SELECT COUNT(*) AS c FROM docids', [], 
				function (t, r) {
					span.textContent = r.rows[0].c;
				}, 
				function (t, e) {
					// couldn't read database
					span.textContent = '(unknown: ' + e.message + ')';
				}
			);
		}
	);
}

void transaction (callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])


When called, this method immediately returns and then asynchronously runs the transaction steps with the transaction callback being the first argument, the error callback being the second argument, if any, the success callback being the third argument, if any, and with no preflight operation or postflight operation. The mode is read/write.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
callback Function to be called when executing SQL statements.

transaction: The transaction to be executed.
errorCallback Function to be called when an SQL error occurs.

error: The SQLError object describing the SQL error that occurred.
successCallback Function to be called when SQL statement is executed successfully.

Properties

readonly String version


The current version of the database.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:05 GMT-0500 (EST)