Class LayoutRestorer

The lifecycle for state restoration is subtle. The sequence of events is:

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

2. Other plugins that care about state restoration require the layout restorer as a dependency.

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

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

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

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

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