38.12 apex.storage namespace

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

Parent topic: JavaScript APIs

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

Parent topic: apex.storage namespace

38.12.2 apex.storage.getCookie

Returns the value of cookie name (pName).

Parameters

Table 38-65 apex.storage.getCookie

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

Returns

The string value of the cookie.

Parent topic: apex.storage namespace

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

Parent topic: apex.storage namespace

38.12.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 38-66 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 38-67 pOptions properties

Name	Type	Description
`prefix`	String	A static prefix string to add to all keys. The default is an empty string.
`useAppId`	Boolean	If `true` the application id will be included in the key The default is `true`.
`usePageId`	Boolean	If `true` the application page id will be included in the key. The default is `false`.
`regionId`	String	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 38-68 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"

Parent topic: apex.storage namespace

38.12.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 38-69 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 38-70 pOptions properties

Name	Type	Description
`prefix`	String	A static prefix string to add to all keys. The default is an empty string.
`useAppId`	Boolean	If `true` the application id will be included in the key The default is `true`.
`usePageId`	Boolean	If `true` the application page id will be included in the key. The default is `false`.
`regionId`	String	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 38-71 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"

Parent topic: apex.storage namespace

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

Parent topic: apex.storage namespace

38.12.7 apex.storage.setCookie

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

Parameters

Table 38-72 apex.storage.setCookie

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

Parent topic: apex.storage namespace