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:
Important usage notes:
To use the SWFStore Utility, include the following source files in your web page:
- <!-- 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>
<!-- 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>
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.)
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):
- <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.
<div id="toBeReplaced" style="width:0px; height:0px"> <br> Unable to load Flash content. The YUI SWFStore Utility requires Flash Player 9.0.115 or higher. <br> </div>
Then, instantiate the SWFStore by passing the
id of this container
<div> to it:
- var swfstore = new YAHOO.util.SWFStore( "toBeReplaced" );
var swfstore = new YAHOO.util.SWFStore( "toBeReplaced" );
The SWFStore has a number of methods that allow the developer to store and retrieve data.
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:
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:
|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.|
Most users will store strings, but any of the core types can be store as well, including
boolean, or even
NULL. Here's a summary of the methods available.
|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
|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:
|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.|
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.
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.
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:
- <allow-access-from url="www.mail.yahoo.com" />
- <allow-access-from url="www.yahoo.com" />
- <allow-access-from url="www.google.com" />
<url-policy> <allow-access-from url="www.mail.yahoo.com" /> <allow-access-from url="www.yahoo.com" /> <allow-access-from url="www.google.com" /> </url-policy>
For further exploration of the swfstore components, take a look at its example files.
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.
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.
All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.