As of this writing there is a lot of noise around HTML5. Given the varying levels of browser support for the new HTML5 features, it’s definitely a question of “who’s on first”.

I’ll attempt to make sense out of one aspect of HTML5, albeit a pretty significant one, that of Client Side Storage. In the Resources Section at the end if this post, there is a link to a working version of the code examples contained herein.

So what does Client Side Storage mean? I thought cookies took care of that.

Cookies are of limited scope and should be used for their intended, specific purpose – they also get sent to the server with each request which is potentially “heavy” if the cookie mechanism is used for non-cookie purposes.

For confirmation, “Client Side Storage” means persisting data inside the browser. The following image provides a snapshot of the SQL database storage – in Chrome, select developer tools to access.

HTML5 Client Side SQL Database

HTML5 has three options for persisting data in the browsers. A related item worth mentioning is the Application Cache. Therefore, items on the agenda for this blog are:

Local Storage
Session Storage
Database Storage (SQL)
Application Cache

Local Storage

This is a key value store designed to persist data, specific to a domain/port, until you delete it. Therefore, it survives browser shutdown. Given that the storage is domain-specific, if you persist some data with a key of “bogus”, it will save different entries for different domains.

NOTE: For both localStorage and sessionStorage, the key and value being must be a string.

Let’s look at some code:

localStorage.setItem("bogus", "100");  // or localStorage.bogus=”100”;
var h = localStorage.getItem("bogus”);
delete localStorage.bogus;

Session Storage

Same as local storage, except it is attached to the browser session and goes away when the session ends. It is worth noting that a distinct session storage is available if you are in a new tab on the same page. The session storage will go away if you (1) Close the tab or (2) Close the browser.

sessionStorage.setItem("bogus ", "100");
var h = sessionStorage.getItem("bogus”);

Database Storage

This is a SQLLite relational database implementation right in the browser. Again, it is attached to the domain. You may also hear this referred to as the Javascript database or web database – the key point is that it is a SQL database variant living inside the browser – really!

To better explain the structure of the code, the following introduces the relevant fragments from the W3C spec (http://dev.w3.org/html5/webdatabase/). Actual code follows thereafter.

Open/Create Database

interface WindowDatabase {
Database openDatabase(
in DOMString name,
in DOMString version,
in DOMString displayName,
in unsigned long estimatedSize,
in optional DatabaseCallback creationCallback
);
};

interface DatabaseCallback {
void handleEvent(in Database database);
};

Sample Code:

var DB_NAME = "webdb_test";
var DB_VERSION = "1.0";
var DB_TITLE   = "Web DB Test";
var DB_BYTES   = 500000;
var db = window.openDatabase(DB_NAME, DB_VERSION, DB_TITLE, DB_BYTES);

Further investigation is warranted, particularly on the “db.changeVersion()” method since it provides a mechanism for DDL and data updates to the client side database … critical if you plan to provide ongoing updates, particularly structural changes.

Statements and Queries

To perform any statements or queries against the database, you need:

Handle to the open database
Transaction Object
SQL Statement

Transaction Object

The following fragments from the spec show the structure of the Transaction component.

interface Database {
void transaction(
in SQLTransactionCallback callback,
in optional SQLTransactionErrorCallback errorCallback,
in optional SQLVoidCallback successCallback);

void readTransaction(
in SQLTransactionCallback callback,
in optional SQLTransactionErrorCallback errorCallback,
in optional SQLVoidCallback successCallback);
}

interface SQLVoidCallback {
void handleEvent();
};

interface SQLTransactionErrorCallback {
void handleEvent(in SQLError error);
}

Sample Code for Transaction and SQL Statements

function createTables(db) {

db.transaction( function(tx) {
var queryParams = [];
tx.executeSql(
"CREATE TABLE IF NOT EXISTS webdocs
(id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, docname VARCHAR(20));",
queryParams,
[],
sqlError
);
}, txError);

}

function createRow(db, docname) {

db.transaction( function(tx) { 

tx.executeSql("INSERT INTO webdocs (docname) VALUES (?);", [  docname ],
function(tx, results) {
var docid     = results.insertId;
var docsAdded = results.rowsAffected;
alert ("docid added: " + docid);
},
sqlError
);
}, txError);
}

The above provides an example of the database transaction and SQL statement. Following is elaboration on the SQL Statement W3C spec.

SQL Statement

interface SQLTransaction {

void executeSql(
in DOMString sqlStatement, 
in optional ObjectArray arguments, 
in optional SQLStatementCallback callback, 
in optional SQLStatementErrorCallback errorCallback);
};

interface SQLStatementCallback {
void handleEvent(in SQLTransaction transaction, 
in SQLResultSet resultSet);
};

interface SQLStatementErrorCallback {
boolean handleEvent(in SQLTransaction transaction, 
in SQLError error);
};

Processing Result Sets

interface SQLResultSet {
readonly attribute long insertId;
readonly attribute long rowsAffected;
readonly attribute SQLResultSetRowList rows;
};

interface SQLResultSetRowList {
readonly attribute unsigned long length;
getter any item(in unsigned long index);
};

Application Cache

This is not the same as “browser cache”. The App Cache facilitates the download and persistence of those “web files” (JS, CSS, HTML, JPG etc.) required to run an app in the browser. Why is this significant?

So you can control which files (CSS, JS, HTML, JPG etc.) really stay in the browser and not be subject to “clear cache” by the user.
Faster startup each time you use the app, since the core aforementioned files can remain there for as long as you specify.
This feature is particularly significant for phone apps – it enables the installation of a browser-based, non-compiled web application on a mobile phone. In this scenario, you have a webapp without needing to write Java, Objective-C and the like for the client-side.
Provides the ability to run and browse “disconnected” from the network since enough of the files are local, allowing you to potentially continue offline.

The code artifact of interest here is: