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: SWFStore

YUI 2: SWFStore

YUI SWFStore Utility is a tool for storing persistent data locally on the client, using the capabilities of the Flash Player. (NOTE: It is not a visual component, and does not generally require a visible SWF.) It is one of the mechanisms used in the YUI Storage Utility, offered here as a standalone component. It has the following differences when compared to a browser cookie:

  1. The data has the ability to persist across multiple browsers. (See Sharing Data Across Browsers)
  2. The amount of data that can be stored is much larger than a cookie. (See settings)
  3. The data has no built-in encryption. (See security)

Important usage notes:

  • The SWFStore Utility does not encrypt data. Data is stored locally in unencrypted binary.
  • The Utility does have a built-in security mechanism to help sandbox your data. See security below.
  • The Utility requires Flash Player 9.0.115 or higher. The latest version of Flash Player is available at the Adobe Flash Player Download Center.

Getting Started

To use the SWFStore Utility, include the following source files in your web page:

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo.js"></script>
  3. <script src="http://yui.yahooapis.com/2.9.0/build/dom/dom.js"></script>
  5. <!-- Source files -->
  6. <script src="http://yui.yahooapis.com/2.9.0/build/swfstore/swfstore.js"></script>
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/dom/dom.js"></script>
<!-- Source files -->
<script src="http://yui.yahooapis.com/2.9.0/build/swfstore/swfstore.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 swfstore. (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.

By default, the file swfstore.swf is expected in the same directory as the HTML page in which a SWFStore Utility instance will appear. We do not host this SWF--you must place a copy of the SWF on your server.

To get started with the SWFStore Utility, begin by placing it on the page. Create a <div> (or other element) placeholder into which you'll render your SWFStore instance. In a typical usage scenario, you can set the width and height of the container to 0, since the SWFStore is a purely functional component and does not have UI of its own (except in the case of settings changes such as requesting a larger data store than 100kb):

  1. <div id="toBeReplaced" style="width:0px; height:0px">
  2. <br>
  3. Unable to load Flash content. The YUI SWFStore Utility requires Flash Player 9.0.115 or higher.
  4. <br>
  5. </div>
<div id="toBeReplaced" style="width:0px; height:0px">
Unable to load Flash content. The YUI SWFStore Utility requires Flash Player 9.0.115 or higher.

Then, instantiate the SWFStore by passing the id of this container <div> to it:

  1. var swfstore = new YAHOO.util.SWFStore( "toBeReplaced" );
var swfstore = new YAHOO.util.SWFStore( "toBeReplaced" );

Using the SWFStore Utility

The SWFStore has a number of methods that allow the developer to store and retrieve data.

Listening for events

In order to receive events from the SWFStore Utility, you need to add event listeners. For example, to add a listener for a save event, do the following:

  1. swfstore.addListener('save',onSave);

This means that when the user saves data, the onSavefunction will be called and an event object will be passed to it. The following events are dispatched by SWFStore:

Event Reason
contentReady dispatched when the SWFStore Flash file has successfully initialized. No event object is passed to the listener function.
save dispatched when the SWFStore has successfully saved data.
error dispatched when the SWFStore is not able to save data.
quotaExceededError dispatched when the SWFStore is attempting to save a large amount of data that exceeds the amount allowed by the user. Please see the settings section for more information.
inadequateDimensions dispatched when the the width and height of the SWFStore SWF is not large enough to display a settings panel.
securityError dispatched when the SWFStore cannot initiatrze due to security restrictions. This is either because the whitelist check failed, or--if there is no whitelist specified--that the calling page's URL does not match the URL of the SWFStore SWF. It can also occur if a local html page is attempting to load the whitelist, as Flash security restrictions will generally not allow this.

SWFStore methods

Most users will store strings, but any of the core types can be store as well, including number, object, boolean, or even NULL. Here's a summary of the methods available.

Method Description
getLength() (number) The number of keys currently stored in the engine.
clear() (function) Clears all keys and the data from the engine.
getValueOf(string) (function) Fetches the data by a key. This method will return a string, number, boolean, or NULL depending on what was provided to setItem.
getValueAt(number) (string) Fetches the key at a given index.
removeItem(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. If size of data requested to be stored is larger than the allotted storage, quotaExceededError may be dispatched. Please see the settings section for more information.
setSize(number) (function) Sets the allotted storage to the requested amount, in KB. Please see the settings section for more information.
calculateCurrentSize() (number) Calculates the amount of storage being used. Note, there is currently no means of determining the current setting for the amount of storage available, only the amount being used.

SWFStore Settings and Requesting more Storage

When attempting to store data above the 100kb default, a Flash Player dialog will attempt to display in the SWF file, which confirms the request for more storage. If the size of the SWF is inadequate, it will not be able to display, an quotaExceededError will be dispatched, and the store will fail. Please see the SWFStore Settings Example for more information on how to prepare your application for this scenario.

Sharing Data Across Browsers

Unlike a browser cookie, SWFStore can share its data across browsers. This is turned off by default, but can be turned on using the shareData parameter. See the SWFStore Advanced Example for an example of this in action.

A Note about Security

To help protect your stored data, only the directory which loaded the swfstore.swf will have access to the data stored in that path. For example, www.badsite.com cannot access data stored via www.goodsite.com/preferences/swfstore.swf. However, the page www.goodsite.com/games.html also cannot access this information. By default, SWFStore will allow subdirectories to access data in the same directory or above. For instance, if the SWF were placed at the top level, www.goodsite.com/swfstore.swf, games.html would have access to it, as would the subdirectory www.goodsite.com/preferences/. If you would like to share stored data across different sites, or you would like more fine-grained control, you can simply place the file storage-whitelist.xml in the same location as the SWFStore.swf file, and within this file detail allowed URLs. The format of the file is the following:

  1. <url-policy>
  2. <allow-access-from url="www.mail.yahoo.com" />
  3. <allow-access-from url="www.yahoo.com" />
  4. <allow-access-from url="www.google.com" />
  5. </url-policy>
    <allow-access-from url="www.mail.yahoo.com" />
    <allow-access-from url="www.yahoo.com" />
    <allow-access-from url="www.google.com" />

SWFStore Examples

For further exploration of the swfstore components, take a look at its example files.

Known Issues

A JavaScript error occurs when the required Flash Player is not present.

When the required Flash Player is not installed on the client's machine, a JavaScript error will accompany the displayed warning message. This is due to a known issue with the YUI SWF Utility used in this version. To review the ticket which includes information on the latest release that addresses this issue, go here.

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.

SWFStore Utility Cheat Sheet:

Cheat Sheet for the SWFStore Utility.

Download full set of cheat sheets.

YUI SWFStore Utility on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings