JSDoc: Namespace: storage

The apex.storage namespace contains all functions related browser storage features such as cookies and session storage.

About local and session storage

Local storage and session storage, collectively known as web storage, are a browser feature that securely stores key value pairs associated with an origin (web site). The keys and values are strings. The amount of storage space for web storage is greater than that of cookies but it is not unlimited. Another advantage over cookies is that the key value pars are not transmitted with each request.

Both local storage and session storage use the same API to set, get, and remove name value pairs. The difference is that session storage goes away when the browser session ends and local storage is available even when the browser restarts. Keep in mind that the browser is free to limit or delete data stored in local storage at the user's request. Unlike data stored on the server local storage is not shared between browsers on different machines or even different browsers on the same machine.

Because APEX supports multiple applications, multiple workspaces and even instances of the same application running in multiple workspaces there can arise conflicts with using web storage because all the apps from a single APEX instance (which is a single origin or web site) share the same web storage space. The apex.storage.getScopedLocalStorage and apex.storage.getScopedSessionStorage solve this problem buy partitioning the storage into a scope based on application id an optionally additional information such as page id and region id. The scope is crated by using a prefix on all the storage keys. This avoids conflicts when different apps or different instances of the same app use the same keys but it is not a secure partition. Consider this carefully before storing sensitive information in web storage.

Functions

(static) getCookie(pName) → {string}

Returns the value of the specified cookie.

Parameters:

Name	Type	Description
`pName`	string	The name of the cookie.

Returns:

The string value of the cookie.

Type: string

Example

Returns the value of the cookie TEST

var value = apex.storage.getCookie( "TEST" );

(static) getScopedLocalStorage(options) → {localStorage}

Returns a thin wrapper around the localStorage object that scopes all keys to a prefix defined by the options parameter. If localStorage is not supported, the returned object can be used but has no effect so it is not necessary test for support using apex.storage.hasLocalStorageSupport before calling this function.

Parameters:

Name Type Description

options

Object

An object used to define the scope of the local storage. This defines the storage key prefix used by the localStorage wrapper object.

Properties

Name	Type	Attributes	Description
`prefix`	string	<optional>	A static prefix string to add to all keys. The default is an empty string.
`useAppId`	boolean	<optional>	Whether the application id will be included in the key. The default is true.
`usePageId`	boolean	<optional>	Whether the application page id will be included in the key. The default is false.
`regionId`	string	<optional>	An additional string to identify a region or other part of a page. The default is an empty string.

Returns:

A localStorage wrapper object.

Type: localStorage

Example

Creates a local storage object that scopes all the keys using a prefix "Acme" and the application id. It then sets and gets an item called "setting1".

var myStorage,
    setting1;
if ( apex.storage.hasLocalStorageSupport() ) {
  myStorage = apex.storage.getScopedLocalStorage({ prefix: "Acme" });
  myStorage.setItem( "setting1", "on" );
  setting1 = myStorage.getItem( "setting1" );
}

(static) getScopedSessionStorage(options) → {sessionStorage}

Returns a thin wrapper around the sessionStorage object that scopes all keys to a prefix defined by the options parameter. If sessionStorage is not supported, the returned object can be used but has no effect so it is not necessary test for support using apex.storage.hasSessionStorageSupport before calling this function.

Parameters:

Name Type Description

options

Object

An object used to define the scope of the session storage. This defines the storage key prefix used by the sessionStorage wrapper object.

Properties

Name	Type	Attributes	Description
`prefix`	string	<optional>	A static prefix string to add to all keys. The default is an empty string.
`useAppId`	boolean	<optional>	Whether the application id will be included in the key. The default is true.
`usePageId`	boolean	<optional>	Whether the application page id will be included in the key. The default is false.
`regionId`	string	<optional>	An additional string to identify a region or other part of a page. The default is an empty string.

Returns:

A sessionStorage wrapper object.

Type: sessionStorage

Example

Creates a session storage object that scopes all the keys using a prefix "Acme" and the application id. It then sets and gets an item called "setting1".

var myStorage,
    setting1;
if ( apex.storage.hasSessionStorageSupport() ) {
  myStorage = apex.storage.getScopedSessionStorage({ prefix: "Acme" });
  myStorage.setItem( "setting1", "on" );
  setting1 = myStorage.getItem( "setting1" );
}

(static) hasLocalStorageSupport() → {boolean}

Returns true if the browser supports the local storage API and false otherwise. Most modern browsers support this feature but some allow the user to turn it off.

Returns:

true if the browser supports the local storage API and false otherwise.

Type: boolean

Example

Sets the local storage "setting1" to on if local storage is supported by the browser.

var myStorage;
if ( apex.storage.hasLocalStorageSupport() ) {
  myStorage = apex.storage.getScopedLocalStorage({ prefix: "Acme" });
  myStorage.setItem( "setting1", "on" );
}

(static) hasSessionStorageSupport() → {boolean}

Returns true if the browser supports the session storage API and false otherwise. Most modern browsers support this feature but some allow the user to turn it off.

Returns:

true if the browser supports the session storage API and false otherwise.

Type: boolean

Example

Sets the session storage "setting1" to on if session storage is supported by the browser.

var myStorage;
if ( apex.storage.hasSessionStorageSupport() ) {
  myStorage = apex.storage.getScopedSessionStorage({ prefix: "Acme" });
  myStorage.setItem( "setting1", "on" );
}

(static) setCookie(pName, pValue)

Sets a cookie to the specified value.

Parameters:

Name	Type	Description
`pName`	string	The name of the cookie.
`pValue`	String	The value to set the cookie to.

Example

Sets the value APEX for the cookie TEST

apex.storage.setCookie( "TEST", "APEX" );

Type Definitions

storageWrapper

A storage wrapper object. This object has the same properties and functions as the native browser Storage interface.

Properties:

Name	Type	Description
`prefix`	string	APEX specific property. The prefix for this scoped storage object.
`length`	number	The number of items in the scoped storage object.
`key`	function	The `key( n )` function returns the nth key in the scoped storage object.
`getItem`	function	The `getItem( key )` function returns the value for the given key.
`setItem`	function	The `setItem( key, data )` function sets the value of the given key to data.
`removeItem`	function	The `removeItem( key )` function removes the given key.
`clear`	function	The `clear` function removes all keys from the scoped storage object.
`sync`	function	The APEX specific `sync` function. Use to ensure the length property is correct if keys may have been added or removed by means external to this object.