YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Storage Utility

YUI 2: Storage Utility

The Storage Utility provides a mechanism for storing significant amounts of textual data, client-side, whether or not your browsers supports the proposed HTML 5 Storage specification.

Each instance of the Storage Utility leverages one of three storage engines in order to store data:

  1. HTML 5: If the client browser supports HTML 5, then this engine will wrap the browser's native storage capability (document.localStorage and document.sessionStorage).
  2. Google Gears: Google Gears is a browser extension that users can install on their machine. One of its features is a SQLite database; the Storage Utility uses this database for client-side storage when using the Gears engine.
  3. SWF: YUI provides a SWFStore Utility that normalizes access to the Flash Shared Object. This is the Storage Utility's fallback engine, which will work on most browsers due to the significant penetration of the Adobe Flash plugin.

YUI Theater: Matt Snider — Introducing the YUI 2.8.0 Storage Utility

Matt Snider, the lead frontend engineer for Mint.com (recently acquired by Intuit), contributed the YUI Storage Utility in the 2.8.0 release. In this session, he provides an overview of the Storage Utility's features and the nuances of the various storage backends.

[More Videos | Transcript]

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:

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js" ></script>
  3. <script src="http://yui.yahooapis.com/2.9.0/build/cookie/cookie-min.js" ></script>
  4. <script src="http://yui.yahooapis.com/2.9.0/build/swf/swf-min.js" ></script>
  5. <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>

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is storage. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

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:

  1. var storageEngine = YAHOO.util.StorageManager.get(
  2. YAHOO.util.StorageEngineHTML5.ENGINE_NAME,
  3. YAHOO.util.StorageManager.LOCATION_LOCAL,
  4. {
  5. force: false,
  6. order: [
  7. YAHOO.util.StorageEngineGears,
  8. YAHOO.util.StorageEngineSWF
  9. ]
  10. });
  11. //storageEngine will be an instance of YAHOO.util.Storage.
var storageEngine = YAHOO.util.StorageManager.get(
        force: false,
        order: [
//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:

  1. // this will fetch the first available engine
  2. var storageEngine = YAHOO.util.StorageManager.get();
  4. storageEngine.subscribe(storageEngine.CE_READY, function() {
  5. storageEngine.setItem('testText', 'this is a triumph');
  6. storageEngine.setItem('testNumber', 1234567890);
  7. storageEngine.setItem('testBoolean', true);
  8. alert(storageEngine.getItem('testText'));
  9. });
// 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);

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:

Configuration Option Purpose
force (boolean) By default the StorageManager will attempt all engines until it finds one that works, but when force is true it will confine itself to the engine specified in the first argument.
order (array) By default the StorageManager will attempt engines in the order that they appear in the code. If you would like to change the order in which storage engines are tried, then add them to this option. This is an array of storage engine classes; the possible values are YAHOO.util.StorageEngineGears, YAHOO.util.StorageEngineSWF, and YAHOO.util.StorageEngineHTML5.
engine (object) The configuration object to pass into the engine.
engine.swfURL (string) For SWFStore, this is the URL of the swfstore.swf; by default /swfstore.swf is used.
engine.containerID (string) For SWFStore, the container into which the SWF will be inserted; by default it is inserted into body element.
engine.attributes (object) For SWFStore, this object will be used by swf.js when creating the SWF object.

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:

Member Contents
length (number) The number of keys currently stored in the engine.
clear() (function) Clears all keys and the data from the engine.
getItem(string) (function) Fetches the data by a key. This method will return a string, number, boolean, or NULL dependending on what was provided to setItem.
getName() (string) Fetches the Storage Engine's name constant.
hasKey(string) (function) Evaluates if the provided key has a value.
key(number) (string) Fetches the key at a given index.
removeKey(string) (function) Removes the key and its value from the engine.
setItem(string, mixed) (function) Adds or updates the value for a given key. The following data types can be stored and returned: string, number, boolean, or NULL.


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

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

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.

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings