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'smoduleName
andkeyName
parameters.Note that
MgrStateHandler
relies uponSyncedSessionStorage
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 todeserializeFromStorage
.
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 providesrestoreStateForKey
and/orrestoreStateForOrd
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 | *
- The Promise or Object returned by the Manager's function, or undefined
-
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 | *
- The Promise or Object returned by the Manager's function, or undefined
-
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 asaveStateForKey
and or asaveStateForOrd
function. ThesaveStateForOrd
function will be used to store information against a particular
ord loaded in the manager, typically to save discovery data. ThesaveStateForKey
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 correspondingrestoreStateForKey
and/orrestoreStateForOrd
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.