Beta Draft: 2016-09-09

30.11 apex.storage namespace

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

30.11.1 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.

30.11.2 apex.storage.getCookie

Returns the value of cookie name (pName).

Parameters


Table 30-51 apex.storage.getCookie

Name Description

pName(String)

The name of the cookie.


Returns

The string value of the cookie.

30.11.3 apex.storage.hasLocalStorageSupport

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.

Parameter

None.

Returns

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

30.11.4 apex.storage.getScopedLocalStorage

Returns a thin wrapper around the localStorage object that scopes all keys to a prefix defined by the pOptions 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.

Parameter


Table 30-52 apex.storage.getScopedLocalStorage

Name Type Description

pOptions

Object

An object that defines the scope of the local storage. This defines the storage key prefix used by the returned localStorage wrapper object. Refer to the following pOptions properties table.



Table 30-53 pOptions properties

Name Description

prefix

A static prefix string to add to all keys. The default is an empty string.

useAppId

If true the application id will be included in the key The default is true.

usePageId

If true the application page id will be included in the key. The default is false.

regionId

An additional string to identify a region or other part of a page.


Returns

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


Table 30-54 localStorage wrapper

Property Description

prefix

APEX specific property. The prefix for this scoped storage object.

length

The number of items in the scoped storage object.

key( n )

Returns the nth key in the scoped storage object.

getItem( key )

Returns the value for the given key.

setItem( key, data )

Sets the value of the given key to data.

removeItem( key )

Removes the given key.

clear:()

Removes all keys from the scoped storage object.

sync()

APEX specific function. Use to ensure the length property is correct if keys may have been added or removed by means external to this object


Example

The following 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 = apex.storage.getScopedLocalStorage( {
    prefix: "Acme",
    useAppId: true 
});
myStorage.setItem( "setting1", "on" );
setting = myStorage.getItem( "setting1" ); // returns "on"

30.11.5 apex.storage.getScopedSessionStorage

Returns a thin wrapper around the sessionStorage object that scopes all keys to a prefix defined by the pOptions 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.

Parameter


Table 30-55 apex.storage.getScopedSessionStorage

Name Type Description

pOptions

Object

An object that defines the scope of the session storage. This defines the storage key prefix used by the returned sessionStorage wrapper object. Refer to the following pOptions properties table.



Table 30-56 pOptions properties

Name Description

prefix

A static prefix string to add to all keys. The default is an empty string.

useAppId

If true the application id will be included in the key The default is true.

usePageId

If true the application page id will be included in the key. The default is false.

regionId

An additional string to identify a region or other part of a page.


Returns

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


Table 30-57 sessionStorage

Property Description

prefix

APEX specific property. The prefix for this scoped storage object.

length

The number of items in the scoped storage object.

key( n )

Returns the nth key in the scoped storage object.

getItem( key )

Returns the value for the given key.

setItem( key, data )

Sets the value of the given key to data.

removeItem( key )

Removes the given key.

clear:()

Removes all keys from the scoped storage object.

sync()

APEX specific function. Use to ensure the length property is correct if keys may have been added or removed by means external to this object


Example

The following 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 = apex.storage.getScopedSessionStorage( {
    prefix: "Acme", useAppId: true 
});
myStorage.setItem( "setting1", "on" );
setting = myStorage.getItem( "setting1" ); // returns "on"

30.11.6 apex.storage.hasSessionStorageSupport

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.

Parameter

None.

Returns

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

30.11.7 apex.storage.setCookie

Sets a cookie (pName) to a specified value (pValue).

Parameters


Table 30-58 apex.storage.setCookie

Name Description

pName (String)

The name of the cookie to set.

pValue (String)

The value to set the cookie to.


Returns

Not applicable.