mozilla

Revision 42585 of DOM Storage guide

  • Revision slug: DOM/Storage
  • Revision title: DOM Storage
  • Revision id: 42585
  • Created:
  • Creator: Mallory
  • Is current revision? No
  • Comment /* Related */

Revision Content

{{template.DomRef()}} {{template.Fx_minversion_header(2)}}

Summary

DOM Storage is the name given to the set of storage-related features introduced in the Web Applications 1.0 specification. DOM Storage is designed to provide a larger, securer, and easier-to-use alternative to storing information in cookies. It is currently only available in Mozilla-based browsers, notably starting with Firefox 2.

Note: DOM Storage is not the same as mozStorage (Mozilla's XPCOM interfaces to SQLite) or the Session store API (an XPCOM storage utility for use by extensions).

Description

The DOM Storage mechanism is a means through which string key/value pairs can be securely stored and later retrieved for use. The goal of this addition is to provide a comprehensive means through which interactive applications can be built (including advanced abilities, such as being able to work "offline" for extended periods of time).

Currently, only Mozilla-based browsers provide a working implementation of the DOM Storage specification. However, Internet Explorer does have a similar feature called "userData behavior" that allows you to persist data across multiple browser sessions.

DOM Storage is useful because no good browser-only methods exist for persisting reasonable amounts of data for any period of time. Browser cookies have limited capacity and provide no support for organizing persisted data, and other methods (such as Flash Local Storage) require an external plugin.

One of the first public applications to make use of the new DOM Storage functionality (in addition to Internet Explorer's userData Behavior) was halfnote (a note-taking application) written by Aaron Boodman. In his application, Aaron simultaneously saved notes back to a server (when Internet connectivity was available) and a local data store. This allowed the user to safely write backed-up notes even with sporadic Internet connectivity.

While the concept, and implementation, presented in halfnote was comparatively simple, its creation shows the possibility for a new breed of web applications that are usable both online and offline.

Reference

The following are global objects that exist as properties of every window object. This means that they can be accessed as sessionStorage or window.sessionStorage. (This is important because you can then use IFrames to store, or access, additional data, beyond what is immediately included in your page.)

sessionStorage

This is a global object (sessionStorage) that maintains a storage area that's available for the duration of the page session. A page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated.

// Save data to a the current session's store
sessionStorage.username = "John";

// Access some stored data
alert( "username = " + sessionStorage.username );

The sessionStorage object is most useful for hanging on to temporary data that should be saved and restored if the browser is accidentally refreshed.

Note: sessionStorage should also be capable of restoring data after the browser has crashed (and been restored), but due to {{template.Bug(339445)}} that doesn't work in Firefox yet. Until this is resolved, the use of sessionStorage as a preventative measure is debatable.

Examples:

Autosave the contents of a text field, and if the browser is accidentally refreshed, restore the text field contents, so that no writing is lost.

 // Get the text field that we're going to track
 var field = document.getElementById("field");
 
 // See if we have an autosave value
 // (this will only happen if the page is accidentally refreshed)
 if ( sessionStorage.autosave ) {
     // Restore the contents of the text field
     field.value = sessionStorage.autosave;
 }
 
 // Check the contents of the text field every second
 setInterval(function(){
     // And save the results into the session storage object
     sessionStorage.autosave = field.value;
 }, 1000);

More information:

globalStorage

This is a global object (globalStorage) that maintains multiple public, and private, storage areas that can be used to hold data over a long period of time (e.g. over multiple pages and browser sessions).

// Save data that only scripts on the mozilla.org domain can access
globalStorage['mozilla.org'].snippet = "<b>Hello</b>, how are you?";

// Save some data that any web page, on any domain, can access
globalStorage[''].favBrowser = "Firefox";

Specifically, the globalStorage object provides access to a number of different storage objects into which data can be stored. For example, if we were to build a web page that used globalStorage on this domain (developer.mozilla.org) we'd have the following storage objects available to us:

  • globalStorage{{mediawiki.external('\'developer.mozilla.org\'')}} - All web pages within the developer.mozilla.org sub-domain can both read and write data to this storage object.
  • globalStorage{{mediawiki.external('\'mozilla.org\'')}} - All web pages with the mozilla.org domain can both read and write to this storage object.
  • globalStorage{{mediawiki.external('\'org\'')}} - All web pages on all .org domains can both read and write to this storage object.
  • globalStorage{{mediawiki.external('<span class=\"plain\"></span>')}} - All web pages on all domains can both read and write to this storage object.
Note: globalStorage{{mediawiki.external('tld')}} and globalStorage{{mediawiki.external('<span class=\"plain\"></span>')}} are presently not implemented by Firefox (throw a security error), due to speculated negative security properties of public read/write access to these namespaces. More information

Examples:

All of these examples require that you have a script inserted (with each of the following code) in every page that you want to see the result on.

Remember a user's username for the particular sub-domain that is being visited:

 globalStorage['developer.mozilla.org'].username = "John";

Keep track of the number of times that a user visits all pages of your domain:

 // parseInt must be used since all data is stored as a string
 globalStorage['mozilla.org'].visits =
     parseInt( globalStorage['mozilla.org'].visits || 0 ) + 1;

Remember all the web sites that you visit:

 globalStorage[''].sites += "," + location.hostname;

More information:

More information

Examples

Related



{{ wiki.languages( { "es": "es/DOM/Almacenamiento", "fr": "fr/DOM/Storage", "ja": "ja/DOM/Storage", "pl": "pl/DOM/Storage" } ) }}

Revision Source

<p>
{{template.DomRef()}}
{{template.Fx_minversion_header(2)}}
</p>
<h3 name="Summary"> Summary </h3>
<p>DOM Storage is the name given to the set of <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#storage">storage-related features</a> introduced in the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/">Web Applications 1.0</a> specification. DOM Storage is designed to provide a larger, securer, and easier-to-use alternative to storing information in cookies. It is currently only available in Mozilla-based browsers, notably starting with <a href="en/Firefox_2">Firefox 2</a>.
</p>
<div class="note"><b>Note:</b> DOM Storage is not the same as <a href="en/Storage">mozStorage</a> (Mozilla's XPCOM interfaces to SQLite) or the <a href="en/Session_store_API">Session store API</a> (an <a href="en/XPCOM">XPCOM</a> storage utility for use by extensions).</div>
<h3 name="Description"> Description </h3>
<p>The DOM Storage mechanism is a means through which string key/value pairs can be securely stored and later retrieved for use. The goal of this addition is to provide a comprehensive means through which interactive applications can be built (including advanced abilities, such as being able to work "offline" for extended periods of time).
</p><p>Currently, only Mozilla-based browsers provide a working implementation of the DOM Storage specification. However, Internet Explorer does have a similar feature called "<a class="external" href="http://msdn.microsoft.com/workshop/author/behaviors/reference/behaviors/userdata.asp">userData behavior</a>" that allows you to persist data across multiple browser sessions.
</p><p>DOM Storage is useful because no good browser-only methods exist for persisting reasonable amounts of data for any period of time.  <a class="external" href="http://en.wikipedia.org/wiki/HTTP_cookie">Browser cookies</a> have limited capacity and provide no support for organizing persisted data, and other methods (such as <a class="external" href="http://www.macromedia.com/support/documentation/en/flashplayer/help/help02.html">Flash Local Storage</a>) require an external plugin.
</p><p>One of the first public applications to make use of the new DOM Storage functionality (in addition to Internet Explorer's userData Behavior) was <a class="external" href="http://aaronboodman.com/halfnote/">halfnote</a> (a note-taking application) written by <a class="external" href="http://aaronboodman.com/">Aaron Boodman</a>. In his application, Aaron simultaneously saved notes back to a server (when Internet connectivity was available) and a local data store. This allowed the user to safely write backed-up notes even with sporadic Internet connectivity.
</p><p>While the concept, and implementation, presented in halfnote was comparatively simple, its creation shows the possibility for a new breed of web applications that are usable both online and offline.
</p>
<h3 name="Reference"> Reference </h3>
<p>The following are global objects that exist as properties of every <a href="en/DOM/window"><code>window</code> object</a>. This means that they can be accessed as <code>sessionStorage</code> or <code>window.sessionStorage</code>. (This is important because you can then use IFrames to store, or access, additional data, beyond what is immediately included in your page.)
</p>
<h4 name="sessionStorage"> <code>sessionStorage</code> </h4>
<p>This is a global object (<code>sessionStorage</code>) that maintains a storage area that's available for the duration of the page session. A page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated.
</p>
<pre class="eval">// Save data to a the current session's store
sessionStorage.username = "John";

// Access some stored data
alert( "username = " + sessionStorage.username );
</pre>
<p>The <code>sessionStorage</code> object is most useful for hanging on to temporary data that should be saved and restored if the browser is accidentally refreshed.
</p>
<div class="bug"><b>Note:</b> <code>sessionStorage</code> should also be capable of restoring data after the browser has crashed (and been restored), but due to {{template.Bug(339445)}} that doesn't work in Firefox yet. Until this is resolved, the use of <code>sessionStorage</code> as a preventative measure is debatable.</div>
<p><b>Examples:</b>
</p><p>Autosave the contents of a text field, and if the browser is accidentally refreshed, restore the text field contents, so that no writing is lost.
</p>
<pre class="eval"> // Get the text field that we're going to track
 var field = document.getElementById("field");
 
 // See if we have an autosave value
 // (this will only happen if the page is accidentally refreshed)
 if ( sessionStorage.autosave ) {
     // Restore the contents of the text field
     field.value = sessionStorage.autosave;
 }
 
 // Check the contents of the text field every second
 setInterval(function(){
     // And save the results into the session storage object
     sessionStorage.autosave = field.value;
 }, 1000);
</pre>
<p><b>More information:</b>
</p>
<ul><li> <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#sessionstorage">sessionStorage specification</a>
</li></ul>
<h4 name="globalStorage"> <code>globalStorage</code> </h4>
<p>This is a global object (<code>globalStorage</code>) that maintains multiple public, and private, storage areas that can be used to hold data over a long period of time (e.g. over multiple pages and browser sessions).
</p>
<pre class="eval">// Save data that only scripts on the mozilla.org domain can access
globalStorage['mozilla.org'].snippet = "&lt;b&gt;Hello&lt;/b&gt;, how are you?";

// Save some data that any web page, on any domain, can access
globalStorage[<span class="plain">''</span>].favBrowser = "Firefox";
</pre>
<p>Specifically, the <code>globalStorage</code> object provides access to a number of different storage objects into which data can be stored. For example, if we were to build a web page that used <code>globalStorage</code> on this domain (developer.mozilla.org) we'd have the following storage objects available to us:
</p>
<ul><li> <code>globalStorage{{mediawiki.external('\'developer.mozilla.org\'')}}</code> - All web pages within the developer.mozilla.org sub-domain can both read and write data to this storage object.
</li><li> <code>globalStorage{{mediawiki.external('\'mozilla.org\'')}}</code> - All web pages with the mozilla.org domain can both read and write to this storage object.
</li><li> <code>globalStorage{{mediawiki.external('\'org\'')}}</code> - All web pages on all .org domains can both read and write to this storage object.
</li><li> <code>globalStorage{{mediawiki.external('&lt;span class=\"plain\"&gt;&lt;/span&gt;')}}</code> - All web pages on all domains can both read and write to this storage object.
</li></ul>
<div class="bug"><b>Note:</b> <code>globalStorage{{mediawiki.external('tld')}}</code> and <code>globalStorage{{mediawiki.external('&lt;span class=\"plain\"&gt;&lt;/span&gt;')}}</code> are presently not implemented by Firefox (throw a security error), due to speculated negative security properties of public read/write access to these namespaces. <a class="external" href="http://ejohn.org/blog/dom-storage-answers/">More information</a></div>
<p><b>Examples:</b>
</p><p>All of these examples require that you have a script inserted (with each of the following code) in every page that you want to see the result on.
</p><p>Remember a user's username for the particular sub-domain that is being visited:
</p>
<pre class="eval"> globalStorage['developer.mozilla.org'].username = "John";
</pre>
<p>Keep track of the number of times that a user visits all pages of your domain:
</p>
<pre class="eval"> // parseInt must be used since all data is stored as a string
 globalStorage['mozilla.org'].visits =
     parseInt( globalStorage['mozilla.org'].visits || 0 ) + 1;
</pre>
<p>Remember all the web sites that you visit:
</p>
<pre class="eval"> globalStorage[<span class="plain">''</span>].sites += "," + location.hostname;
</pre>
<p><b>More information:</b>
</p>
<ul><li> <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#globalstorage">globalStorage specification</a>
</li></ul>
<h3 name="More_information"> More information </h3>
<ul><li> <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/">Web Applications 1.0 Specification</a>
</li><li> <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#storage">Web Applications 1.0 Storage Specification</a>
</li><li> <a class="external" href="http://kb.mozillazine.org/Dom.storage.enabled">Enable/Disable DOM Storage in Firefox or SeaMonkey</a>
</li></ul>
<h3 name="Examples"> Examples </h3>
<ul><li> <a class="external" href="http://channy.creation.net/work/firefox/domstorage/">Basic DOMStorage Examples</a>
</li><li> <a class="external" href="http://aaronboodman.com/halfnote/">halfnote</a> - Note writing application that uses DOM Storage.
</li></ul>
<h3 name="Related"> Related </h3>
<ul><li> <a class="external" href="http://en.wikipedia.org/wiki/HTTP_cookie">HTTP cookies</a> (<code><a href="en/DOM/document.cookie">document.cookie</a></code>)
</li><li> <a class="external" href="http://www.macromedia.com/support/documentation/en/flashplayer/help/help02.html">Flash Local Storage</a>
</li><li> <a class="external" href="http://msdn2.microsoft.com/en-us/library/ms531424.aspx">Internet Explorer userData behavior</a>
</li></ul>
<p><br>
</p><p><br>
</p>
<div class="noinclude"><a href="en/Cn/DOM/Storage">cn:DOM:Storage</a>
</div>
{{ wiki.languages( { "es": "es/DOM/Almacenamiento", "fr": "fr/DOM/Storage", "ja": "ja/DOM/Storage", "pl": "pl/DOM/Storage" } ) }}
Revert to this revision