Module: nmodule/webEditors/rc/wb/mgr/MgrStateHandler

API Status: Development

MgrStateHandler provides the ability to save some state for a Manager view, allowing, at
the most basic level, a Manager to preserve the state of its hidden/visible columns
and the visibility of the learn table when moving between views. Managers may also
optionally use it to remember other state, such as the items that were found during
the last discovery action.

Note that although it provides similar functionality to the Java MgrState type, it differs
in that this type is not used to preserve the state on its own instance. This type provides
the functionality to serialize and deserialize the data to JSON; the object instance itself
does not store any state and is not preserved between hyperlinks or page reloads.

A Manager may provide its own functions that can be used to save and restore custom data
for a particular Manager type. See the description of the save() function for information.


new (require("nmodule/webEditors/rc/wb/mgr/MgrStateHandler"))()

Constructor not to be called directly. Call .make() instead.

Methods


<static> make(params)

Takes a key string that will be used to index the
state information in the storage. This key is usually derived from
the Manager widget's moduleName and keyName parameters.

Note that MgrStateHandler relies upon SyncedSessionStorage which can
take up to 1000ms to initialize, so this may take that long to resolve.

Parameters:
Name Type Description
params Object

the parameters object or a string containing the
key parameter.

Properties
Name Type Description
key String

the key name used to index the saved state
information. Usually derived from the Manager's moduleName and keyName
parameters.

Returns:
Type
Promise.<module:nmodule/webEditors/rc/wb/mgr/MgrStateHandler>

deserializeFromStorage()

Retrieve the state from storage and return the state object. This will be called
early in the manager's load process in order for it to be able to access relevant
state before the model is created. The object returned from this method will be
passed back to the restore function later in the load process.

Returns:
  • the stored state deserialized from JSON.
Type
Object

doRestore(mgr, obj)

Use the deserialized object to restore the state of the manager.
This will restore the basic state, then invoke the custom functions on the
manager itself, if they are defined.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being restored.

obj Object

the object containing the state to be restored

Returns:
Type
Promise

doSave(mgr, state)

Save the Manager's state to the given object, prior to serialization.
This will save the basic state supported for all Manager views, and then
try to see if the Manager provides its own functions for saving custom
data.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being saved.

state Object

an object instance that will contain the state to be serialized.


restore(mgr, state)

Restore the state of a Manager. This function will retrieve the stored
state information from session storage using the Manager's key. It takes a
deserialized state object returned from an earlier call to deserializeFromStorage.
The properties of that object will then be used to restore the prior
state.

The default restore implementation will restore the visibility of the table
columns and the discovery tables. If the Manager provides restoreStateForKey and/or
restoreStateForOrd functions to correspond to the save functions, these will be
called with the deserialized versions of the objects the save functions returned.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being restored.

state Object

a deserialized state object with properties containing the state to be restored.

Returns:
  • A promise resolved when the state restoration has completed.
Type
Promise
Example

Add a function on the Manager to restore the items found in the last discovery.

MyDeviceMgr.prototype.restoreStateForOrd = function (state) {
  if (state.discoveries) {
    this.discoveredItems = state.discoveries;
  }
  return this.reloadLearnModel(); // Returns a Promise that will reload the table
};

restoreForKey(mgr, obj)

Test whether the Manager has a restoreStateForKey function, and invoke it, if found.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being restored.

obj Object

the object containing the state to be restored

Returns:
  • The Promise or Object returned by the Manager's function, or undefined
    if the manager does not provide the function.
Type
Promise | *

restoreForOrd(mgr, obj)

Test whether the Manager has a restoreStateForOrd function, and invoke it, if found.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being restored.

obj Object
Returns:
  • The Promise or Object returned by the Manager's function, or undefined
    if the manager does not provide the function.
Type
Promise | *

save(mgr)

Save the state of the Manager to session storage. This will perform three steps:
first the manager's state is saved as properties upon a state object, secondly the
object is serialized to JSON, and finally the JSON string is placed in session storage.

The default save implementation will save the common basic state of the manager;
that is the visibility of the table columns and the visibility of the discovery table.
The manager can also provide functions to save state, which will be called by
this type, if defined. The manager may provide a saveStateForKey and or a saveStateForOrd
function. The saveStateForOrd function will be used to store information against a particular
ord loaded in the manager, typically to save discovery data. The saveStateForKey function
can be used to save generic data for the type of Manager. Both of these functions
should return an Object containing the state to save. The returned value will
be added to the data to be serialized. The Manager should also provide corresponding
restoreStateForKey and/or restoreStateForOrd functions that will receive a
deserialized version of the object.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance requiring its state to be saved.

Returns:
Type
Promise
Example

Add a function on the Manager to save the items found in the last discovery.

MyDeviceMgr.prototype.saveStateForOrd = function () {
  return {
    discoveries: this.discoveredItems // These objects will be serialized as JSON
  };
};

saveForKey(mgr, state)

Test whether the Manager has a saveStateForKey function, and invoke it, if found.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being saved.

state Object

an object instance that will contain the state to be serialized.


saveForOrd(mgr, state)

Test whether the Manager has a saveStateForOrd function, and invoke it, if found.

Parameters:
Name Type Description
mgr module:nmodule/webEditors/rc/wb/mgr/Manager

the Manager instance being saved.

state Object

an object instance that will contain the state to be serialized.