The lifecycle for state restoration is subtle. The sequence of events is:
The layout restorer plugin is instantiated and makes a fetch call to
the data connector that stores the layout restoration data. The fetch
call returns a promise that resolves in step 6, below.
Other plugins that care about state restoration require the layout
restorer as a dependency.
As each load-time plugin initializes (which happens before the front-end
application has started), it instructs the layout restorer whether
the restorer ought to restore its widgets by passing in its widget
tracker.
Alternatively, a plugin that does not require its own widget tracker
(because perhaps it only creates a single widget, like a command palette),
can simply add its widget along with a persistent unique name to the
layout restorer so that its layout state can be restored when the lab
application restores.
After all the load-time plugins have finished initializing, the front-end
application started promise will resolve. This is the first
promise that the layout restorer waits for. By this point, all of the
plugins that care about restoration will have instructed the layout
restorer to restore their widget trackers.
The layout restorer will then instruct each plugin's widget tracker
to restore its state and reinstantiate whichever widgets it wants. The
tracker returns a promise to the layout restorer that resolves when it
has completed restoring the tracked widgets it cares about.
As each widget tracker finishes restoring the widget instances it cares
about, it resolves the promise that was returned to the layout restorer
(in step 5). After all of the promises that the restorer is awaiting have
settled, the restorer then resolves the outstanding fetch promise
(from step 1) and hands off a layout state object to the application
shell's restoreLayout method for restoration.
Once the application shell has finished restoring the layout, the
JupyterLab application's restored promise is resolved.
Of particular note are steps 5 and 6: since data restoration of plugins
is accomplished by executing commands, the command that is used to restore
the data of each plugin must return a promise that only resolves when the
widget has been created and added to the plugin's widget tracker.
The default implementation of a layout restorer.
Notes
The lifecycle for state restoration is subtle. The sequence of events is:
The layout restorer plugin is instantiated and makes a
fetch
call to the data connector that stores the layout restoration data. Thefetch
call returns a promise that resolves in step 6, below.Other plugins that care about state restoration require the layout restorer as a dependency.
As each load-time plugin initializes (which happens before the front-end application has
started
), it instructs the layout restorer whether the restorer ought torestore
its widgets by passing in its widget tracker. Alternatively, a plugin that does not require its own widget tracker (because perhaps it only creates a single widget, like a command palette), can simplyadd
its widget along with a persistent unique name to the layout restorer so that its layout state can be restored when the lab application restores.After all the load-time plugins have finished initializing, the front-end application
started
promise will resolve. This is thefirst
promise that the layout restorer waits for. By this point, all of the plugins that care about restoration will have instructed the layout restorer torestore
their widget trackers.The layout restorer will then instruct each plugin's widget tracker to restore its state and reinstantiate whichever widgets it wants. The tracker returns a promise to the layout restorer that resolves when it has completed restoring the tracked widgets it cares about.
As each widget tracker finishes restoring the widget instances it cares about, it resolves the promise that was returned to the layout restorer (in step 5). After all of the promises that the restorer is awaiting have settled, the restorer then resolves the outstanding
fetch
promise (from step 1) and hands off a layout state object to the application shell'srestoreLayout
method for restoration.Once the application shell has finished restoring the layout, the JupyterLab application's
restored
promise is resolved.Of particular note are steps 5 and 6: since data restoration of plugins is accomplished by executing commands, the command that is used to restore the data of each plugin must return a promise that only resolves when the widget has been created and added to the plugin's widget tracker.