Getting Started

The Storage Utility is dependant on the Yahoo Global Object, Dom, and Event. Optionally, if you wish to use session storage, then include Cookie, and if you plan to use SWF storage include SWF Store and its dependencies. In a common implementation that relied on both session storage and SWFStore, you would include the following source files in your web page:

<!-- Dependencies --> 
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/cookie/cookie-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/swf/swf-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/storage/storage-min.js" ></script>
 

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/cookie/cookie-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/swf/swf-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/storage/storage-min.js" ></script>
 

With the Storage Utility present, you can now store large amounts of data on the client's machine. But first you must retrieve an engine instance by calling StorageManager.get with the following optional arguments:

1. engineType: The textual name of the engine which you would like try first; by default if this engine doesn't exist, the system will try the other engines; these names are found at the StorageEngineType.ENGINE_NAME constants. Currently, you can choose from YAHOO.util.StorageEngineGears, YAHOO.util.StorageEngineSWF, and YAHOO.util.StorageEngineHTML5.
2. location: The location where you would like to store data, either session or local; local remains between sessions, while session data clears when the user closes her browser.
3. conf: The configuration object can be used to change the behavior of StorageManager.get and/or the engines instantiated.

A sample instantiation might look like this:

var storageEngine = YAHOO.util.StorageManager.get(
    YAHOO.util.StorageEngineHTML5.ENGINE_NAME,
    YAHOO.util.StorageManager.LOCATION_LOCAL,
    {
        force: false,
        order: [
            YAHOO.util.StorageEngineGears,
            YAHOO.util.StorageEngineSWF
        ]
    });
//storageEngine will be an instance of YAHOO.util.Storage.
 

var storageEngine = YAHOO.util.StorageManager.get(
    YAHOO.util.StorageEngineHTML5.ENGINE_NAME,
    YAHOO.util.StorageManager.LOCATION_LOCAL,
    {
        force: false,
        order: [
            YAHOO.util.StorageEngineGears,
            YAHOO.util.StorageEngineSWF
        ]
    });
//storageEngine will be an instance of YAHOO.util.Storage.
 

General Usage Pattern

The following is the general code pattern used to fetch an engine, then write/read some data:

// this will fetch the first available engine
var storageEngine = YAHOO.util.StorageManager.get();
 
storageEngine.subscribe(storageEngine.CE_READY, function() {
    storageEngine.setItem('testText', 'this is a triumph');
    storageEngine.setItem('testNumber', 1234567890);
    storageEngine.setItem('testBoolean', true);
    alert(storageEngine.getItem('testText'));
});
 

// this will fetch the first available engine
var storageEngine = YAHOO.util.StorageManager.get();
 
storageEngine.subscribe(storageEngine.CE_READY, function() {
    storageEngine.setItem('testText', 'this is a triumph');
    storageEngine.setItem('testNumber', 1234567890);
    storageEngine.setItem('testBoolean', true);
    alert(storageEngine.getItem('testText'));
});
 

Configuring the Storage Utility

The Storage Utility is configured via the third argument to the get method. This optional argument is an object containing one or more of the following fields:

Using A Storage Engine

Once a storage engine has been instantiated, the engine instance can be used to write and read data from the engine. Mostly strings should be stored, but we have added meta data to allow the storing of number, boolean, or NULL as well. Here's a summary of the methods available on the engine object:

Limitations

Each storage engine has its own restrictions and limitations. The engine files themselves make note of these restrictions, but here is a summary:

HTML 5 Storage Engine

1. Only the most recent versions of browsers support HTML 5 storage: FireFox 3, Safari 4, and IE 8;
2. IE 8 allows 10 MB of storage, but other browsers only allow 5 MB;

Gears Storage Engine

1. Gears uses SQLite, which has limitations; see the SQLite limitations article on SQLite.org for more information;
2. The end user must approve a site to use Gears;
3. Cookies must be used to emulate session storage;
4. SQLite only supports about 2 GB worth of data;
5. Under the hood, large strings must be fragmented as there is a limit to the number of characters that can be written per SQL statement;

SWF Storage Engine

1. SWF data is stored in a shared SWF object, which can be located and read on the filesystem;
2. When more than 100kb of data is stored, the end user must approve a size increase;
3. Cookies must be used to emulate session storage;
4. There is a timing delay while the SWF loads; therefore, the CE_READY custom event must be subscribed to before using engine;
5. Flash will need to be installed and active on the end-user's browser (although most end-users have Flash installed);

YUI on Mobile: Using Storage Utility with "A-Grade" Mobile Browsers

The Storage Utility is fully supported on Apple's iPhone, which implements the HTML 5 storage proposal. We have not tested the Storage Utility against other devices in this class.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.