Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master

This branch is 8 commits behind elijahmanor:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
demo
test
amplify.store.js
readme.md

readme.md

amplify.store

amplify.store is a wrapper for various persistent client-side storage systems. amplify.store supports IE 5+, Firefox 2+, Safari 4+, Chrome, Opera 10.5+, iPhone 2+, Android 2+ and provides a consistent API to handle storage cross-browser.

amplify.store is meant to allow you to utilize all the latest storage technologies for those browsers that have them, while gracefully degrading for those without support. amplify.store allows you to be passive or explicit in the storage technologies used. With no storage type explicitly specified, amplify.store will go through a series of technologies and pick an appropriate storage technology through feature detection. amplify.store also handles serializing to and from a JavaScript object using JSON serialization where necessary.

Note: Because of the JSON dependency, you need to add json2.js for support in browsers without native JSON support, including IE 5, IE 6, IE 7, Firefox 2.0 and Firefox 3.0.

Usage

amplify.store( string key, mixed value [, hash options ] )

Stores a value for a given key using the default storage type.

  • key: Identifier for the value being stored.
  • value: The value to store. The value can be anything that can be serialized as JSON.
  • [options]: A set of key/value pairs that relate to settings for storing the value.
amplify.store( string key )

Gets a stored value based on the key.

amplify.store()

Gets a hash of all stored values.

amplify.store( string key, null )

Clears key/value pair from the store.

amplify.store.storageType( string key, mixed value [, hash options ] )

Stores a value for a given key using an explicit storage type, where storageType is one of the available storage types through amplify.store. The storage types available by default are listed below.

amplify.store.storageType( string key )

Gets a stored value based upon key for the explicit storage type.

amplify.store.storageType()

Gets a hash of all stored values which were stored through amplify.store.

Options

  • expires: Duration in milliseconds that the value should be cached.

Storage Types

Support for the following storage types are built into amplify.store and are detected in the order listed. The first available storage type will become the default storage type when using amplify.store().

localStorage

  • IE 8+
  • Firefox 3.5+
  • Safari 4+
  • Chrome
  • Opera 10.5+
  • iPhone 2+
  • Android 2+

sessionStorage

  • IE 8+
  • Firefox 2+
  • Safari 4+
  • Chrome
  • Opera 10.5+
  • iPhone 2+
  • Android 2+

globalStorage

  • Firefox 2+

userData

  • IE 5 - 7
    • userData stores are available only in the same directory used to store the data.
    • userData exists in newer versions of IE as well, but due to quirks in IE 9's implementation, we don't register userData if localStorage is supported.

memory

An in-memory store is provided as a fallback if none of the other storage types are available.

Examples

Store data with amplify storage picking the default storage technology:

amplify.store( "storeExample1", { foo: "bar" } );
amplify.store( "storeExample2", "baz" );
// retrieve the data later via the key
var myStoredValue = amplify.store( "storeExample1" ),
    myStoredValue2 = amplify.store( "storeExample2" ),
    myStoredValues = amplify.store();
myStoredValue.foo; // bar
myStoredValue2; // baz
myStoredValues.storeExample1.foo; // bar
myStoredValues.storeExample2; // baz

Open this example in jsFiddle

Store data explicitly with session storage

amplify.store.sessionStorage( "explicitExample", { foo2: "baz" } );
// retrieve the data later via the key
var myStoredValue2 = amplify.store.sessionStorage( "explicitExample" );
myStoredValue2.foo2; // baz

Open this example in jsFiddle

Known Issues

userData (IE 5 - 7) key names are not preserved

Keys for userData stores are restricted to valid XML names. As a result, invalid keys are sanitized prior to setting or getting a value. This generally works as expected, but if you store a value using an invalid key then getting the full store via amplify.store() will return the sanitized keys instead of the original keys. See Names and Tokens, W3C XML Naming for full details on valid XML names.

Something went wrong with that request. Please try again.