QtWebKit Guide - Client Storage

Storing Non-String Data

Since local and session storage APIs only support string values, you need to be careful not to allow errors that result from passive conversions from other data types. The following sample shows how such an error might come about:

     var db = window.localStorage;
     var saveCardInfo;
         // user expresses preference NOT to save credit card info:
     saveCardInfo = false;
         // BUG happens here...
     db.setItem("save_card_info", saveCardInfo);
         // variable is now a string, not a boolean:
     saveCardInfo = db.getItem("save_card_info");
         // both "true" and "false" strings evaluate as true...
     if ( saveCardInfo ) {
         // ...so this code always executes...
     }
     else {
         // ...and this code never executes.
     }

The user's preference to retain credit card information is expressed within the application as a true or false boolean value. When each value is passed to storage, however, it is passively converted to a string. When reassigned to a JavaScript variable, it no longer serves as a valid boolean test. The application falsely assumes users want to save credit card information, regardless of their expressed preference.

The following sample fixes the problem. Instead of using true and false boolean values, it converts 1 and 0 strings to numbers:

     var db = window.localStorage;
     var saveCardInfo = 0;
     db.setItem("save_card_info", saveCardInfo);
     // multiplying forces numeric output:
     saveCardInfo = db.getItem("save_card_info") * 1;

For a more reliable alternative, store values as JSON strings and rely on automatic type conversion when subsequently parsing them. The following sample shows how parsing JSON preserves both boolean and numeric data:

     var saveCardInfo = true;                    // boolean
     var shipMethod = 2;                        // number
     var db = window.localStorage;

     db.setItem("save_card_info", JSON.stringify(saveCardInfo));
     db.setItem("ship_method", JSON.stringify(shipMethod));

     saveCardInfo = JSON.parse(db.getItem("save_card_info"));    // boolean
     shipMethod = JSON.parse(db.getItem("ship_method"));        // number

Note that this simple approach may cause problems of its own. For example, perhaps the words true and false really should be represented as strings. Encapsulating data within objects accounts for such variability:

     var db = window.localStorage;
     var obj = {
         bool    : true,
         str        : "true",
         num        : 1
     };
     db.setItem("appState", JSON.stringify(obj));    // to database...
     // "appState" is "{'bool':true,'num':1,'str':'true'}"
     obj = JSON.parse(db.getItem("appState"));    // ...and back
     // obj is same as initially defined.

The ability to save objects as JSON strings means that you can save an application's state within a single database field. For example, you might use the following approach to save the entire contents of a shopping cart in a single field for later use:

     var db = window.localStorage;
     var cart = { items: [] };

     cart.message = "From your loving uncle";

     cart.items.push({
         description    : "Floor to Ceiling Shoe Rack",
         id        : 203174676,
         price    : 99.95,
         quantity    : 1,
         weight    : 20,
     });

     cart.items.push({
         description    : "Automatic Laser Toy for Cats",
         id        : 203345371,
         price    : 19.95,
         quantity    : 2,
         weight    : 0.5,
     });

     // save all cumulative items:
     db.setItem("cart", JSON.stringify(cart));

     // extract items from storage:
     cart = JSON.parse(db.getItem("cart"));

JSON allows you to store data types, but functions are ignored. That makes it more difficult to preserve objects representing fully functional applications.

     window.addEventListener("storage", function(event){
         var icon = document.querySelector("#indicator");
         if (event.storageArea.length) {
             icon.className = "writing";
         }
         else {
             icon.className = "empty";
         }
     }, false);

 if (!!window.openDatabase) {
     // supports WebSQL
 }

     var db = openDatabase('mydb', '1.0', 'my first database', 2*1024*1024);
     var db = openDatabase('notes', '', 'The Example Notes App!', 1048576);

     var version = db.version;

     db.transaction(function (tx) {
       // SQL details on the tx object go here
     }

     var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
     db.transaction(function (tx) {
         tx.executeSql('CREATE TABLE IF NOT EXISTS foo (id unique, text)');
         tx.executeSql('INSERT INTO foo (id, text) VALUES (1, "synergies")');
     });

     tx.executeSql('INSERT INTO foo (id, text) VALUES (?, ?)', [id, value]);

     tx.executeSql('SELECT * FROM foo', [], function(tx, results) {
         for (var i = 0 , len = results.rows.length; i < len; i++) {
             // do something with results.rows.item(i).text
         }
     });

     if (db.version == "1.0") {
         try {
             // comment out for crash recovery.
             db.changeVersion("1.0", "2.0", cv_1_0_2_0, oops_1_0_2_0, success_1_0_2_0);
         } catch(e) {
             alert('changeversion 1.0 -> 2.0 failed');
             alert('DB Version: '+db.version);
         }
     }