Hack 36. Use Permanent Client-Side Storage for Ajax Applications

Use an open source framework that allows applications to store large amounts of data persistently on the client side.

This hack describes the Ajax Massive Storage System (AMASS). AMASS is an open source library that uses a hidden Flash applet to allow JavaScript Ajax applications to store an arbitrary amount of sophisticated information on the client side. This information is permanent and persistent; if the user closes the browser or navigates away from the web site, the information is still present and can be retrieved later by the web page. Information stored by web pages is private and locked to a single domain, so other web sites cannot access this information.

AMASS makes it possible to store an arbitrary amount of sophisticated data, past the 4K limit of cookies or the 64K limit of Internet Explorer's proprietary client-side storage system.

See the site http://codinginparadise.org/weblog/2005/08/ajax-internet-explorer-has-native.html for details on Internet Explorer's 64K storage system.

An AMASS-enabled web site can store up to 100K of data without user permission. Above that limit, the web site must prompt users for permission to store the requested amount of information. The AMASS system informs the client-side application whether the storage request was allowed or denied. In tests, AMASS has been able to store up to 10 MB of user data with good performance.

AMASS works on Internet Explorer 6+ and Gecko-based browsers such as Firefox. Users must have Version 6+ of the Flash plug-in installed to use AMASS, but according to Macromedia's statistics (http://www.macromedia.com/software/player_census/flashplayer/), Flash 6+ is already installed on 95% of machines.

The latest release of AMASS can be found at http://codinginparadise.org/projects/storage/latest.zip; at the time of publication the latest release of AMASS was Version 0.02 and was in alpha development. AMASS is under a BSD license.

Using AMASS

Working with AMASS is simple. The AMASS framework creates the abstraction of a permanent hash table that persists even after the user has left the page or closed the browser.

The first step in working with AMASS is to load the AMASS script:

<!-- Load the Permanent Storage framework --> <script src="/books/4/254/1/html/2/storage.js"></script>

In order to use AMASS, you must wait for its internal machinery to finish loading. To find out when this happens, add a listener:

storage.onLoad(initialize); function initialize(  ) { }

Once AMASS is loaded, you can begin to work with it by using its hash table methods, such as put( ), get( ), and hasKey( ):

var keyName = "message"; var keyValue = new Object(  ); keyValue.message = "hello world"; keyValue.testArray = ["test1", "test2", "test3"]; keyValue.testObject = {someProperty: "someValue"}; if (storage.hasKey(keyName) == false) {     storage.put(keyName, keyValue, statusHandler); } else {     var results = storage.get(keyName); }

The AMASS framework makes it possible to serialize entire JavaScript objects into the storage system, such as the keyValue object we serialized earlier. Note that DOM nodes and browser objects such as the XMLHttpRequest object will not be serialized.

As mentioned earlier, applications can store up to 100K of data without user permission. After this, a pop-up is generated by the underlying Flash system that prompts the user for permission. The AMASS framework knows when the pop-up appears, generating a div and bringing the Flash file to the forefront of the application. Figure 4-12 shows the application centering the pop-up on the screen.

Figure 4-12. Asking permission to store large data amounts

Users can either approve or deny a storage request, so you must create your application so that it's ready if its storage request is denied. The put( ) method takes as its third argument a status handler that informs your code whether the storage request was successful or not. In the following code, statusHandler( ) is a callback function that receives the outcome of whether the request succeeded or failed:

function statusHandler(status) {     if (status == Storage.SUCCESS) {         var results = storage.get(keyName);         alert("Results from statusHandler="+results);     }     else if (status == Storage.PENDING) {         alert("Results pending approval of storage space from user");     }     else if (status == Storage.FAILED) {         alert("Storage request denied");     } };

status can be one of three values: Storage.SUCCESS, Storage.PENDING, or Storage.FAILED. If the pop-up appears, you will get a callback of Storage.PENDING. Later, if the user approves the request, you will receive Storage.SUCCESS; if the request is denied, you will receive Storage.FAILED. Upon approving the request, users can also indicate whether they give permission to future requests to automatically store information without the application popping up the permission dialog again.

How AMASS Works Internally

Internally, AMASS uses a hidden Flash file and Flash's SharedObject functionality to permanently store the information. AMASS scripts the Flash applet using the Flash plug-in's ActiveX methods on Internet Explorer and its LiveConnect methods on Firefox. AMASS then uses the Flash SharedObject's callbacks to detect when the request storage dialog is on the screen and pass these back to the JavaScript application.

Brad Neuberg