Workspaces
When Finsemble starts, it automatically re-launches the apps that the user last used, and places them in the same position and with the same state. This is called a workspace. Users can create and save multiple workspaces and easily switch between them.
In other words, a workspace is simply a collection of apps that persist between sessions.
What types of apps live in the workspace?
Only apps are stored in workspace. UI components such as menus, toolbars, dialogs, and chat windows are not stored in the workspace.
In the next diagram, the red components are workspace independent. They are not stored in a workspace. The blue
components are apps. They are part of the workspace and will get restored at the proper position when a new session starts.
Setting default workspaces
By default, your users begin with an empty workspace, but you can define default workspaces that contain apps of your choosing by creating a workspaces config entry. This entry is an array. Here is Finsemble's default:
"workspaces": [
{
"version": "1.0.0",
"name": "Default Workspace",
"type": "workspace",
"groups": {},
"windows": []
}
]
You can add any number of workspaces to the array. Each workspace contains a set of windows that describe the apps that are part of the workspace and their positions. The groups section defines windows that have been grouped together.
Workspaces defined by the config are persistent. If an end user deletes them locally, they will be recreated from the config the next time Finsemble restarts.
It would be a lot of work to manually create this config, so instead we use Fisemble's "workspace export" tool to generate it:
- Add the workspaces config from earlier to
public/configs/application/config.json. - Open up Finsemble and create the workspace you want.
- Open the preferences menu (from the FileMenu) and click on "Workspaces". Export the workspace.
- Copy the exported workspace's configuration to your
workspacesconfig entry.
Now, when you deploy Finsemble your new users will be initialized with the workspace that you just created.
You can also export workspaces using FSBL.Clients.WorkspaceClient.export().
The "active workspace"
Finsemble maintains a special workspace called the active workspace, which represents the current state of the user's desktop. When a user restarts Finsemble, it is the active workspace that is restored. The active workspace begins as a clone of a saved workspace that is created when the user switches from one workspace to another.
By default, changes to the active workspace are not saved back to the saved workspace until the user closes Finsemble and selects yes when prompted about saving. See Workspace Service config for configuring dirty workspace behavior.
The active workspace is stored using the StorageClient topic finsemble.workspace.cache. Don't send this topic through a remote storage adapter. A message is sent on this topic every time an end user makes a change to a window on the screen. We recommend that this topic be allowed to flow to Finsemble's default IndexedDB storage adapter.
When saved, a workspace's config is broadcast on the StorageClient topic finsemble.workspace. This can safely be handled by a remote storage adapter.
See the StorageClient topics in the config reference.
Setting up workspace auto-save
Normally, if a user changes something in the workspace and then shuts down or restarts their desktop, Finsemble asks the user whether to save the changes to the workspace. But this action is configurable.
To auto-save a workspace without user input you set the finsemble.servicesConfig.workspace.promptUserOnDirtyWorkspace property to false in the config.json file. When you set this property, Finsemble won't ask the user whether they want to save their workspace before shutting down or restarting. Specifically, Finsemble automatically saves the workspace if one of these occurs:
- Finsemble is shutting down
- Finsemble is restarting
- User is reloading the current workspace
- User is switching from the current workspace to another one
Finsemble auto-saves workspaces only if the finsemble.servicesConfig.workspace.discardUnsavedChanges property is either not set (thus defaulting to false) or explicitly set to false. If this property is set to true, the workspace data will be the one from when the workspace was last saved and any unsaved changes will be lost.
Each user can also configure auto-save for themselves. To do so, they access the Workspaces panel in the Preferences, as shown here:
Adapting workspaces to different monitor configurations
This feature is experimental in Finsemble 8.7. It might change substantially over time or it might not be supported in the future. Use at your own risk.
By default, window bounds are stored in workspaces with dimensions set in pixels, allowing them to be restored at the same size and shape. If the workspace is restored on a system with different monitor sizes or configurations, its windows will retain the same dimensions, meaning that they may take up more or less of the available space on the monitor and that Finsemble may need to alter the layout to ensure that none of the windows are lost offscreen.
Alternatively, Finsemble can be configured to store window bounds as percentages of the available space on the monitor they are displayed on instead. This allows the workspace's windows to be restored on a different monitor configuration and produce approximately the same layout scaled to each monitor's dimensions. For example, a window might take up the top left corner of a monitor (50% width and height, from the top left edge) and will be restored at that position and those proportions on any monitor it is loaded on.
To enable this setting, set the finsemble.servicesConfig.workspace.workspaceAsPercent property to true in your public/configs/application/config.json file. This is a global setting that will enable or disable this feature for all of Finsemble. Percentage values will be written to a workspace on save if the feature is enabled. Similarly, if a workspace is restored when this feature is enabled, percentage values will be used (if present in the workspace) to determine spawn locations of windows.
Minimum width and height settings for each window will be respected. If a percentage value for a window bound would end up below these values, the minimum will be substituted instead and this value will be used to calculate a new percentage. This may cause groups to break or the layout to be otherwise altered. If this behaviour is not desirable, make sure minimum values are not set in the configuration of your apps or are set to small enough values to handle the variation in your monitor setups. Keep in mind a very small width or height on a small monitor may leave the window unusable.
Managing component states
Earlier we have seen that workspaces automatically keep a record of a user's window positions and sizes. In addition, for each component or app the workspace can also store its component state, which is internal data about the component. Component state makes it possible to store the working information about the app or component, which allows users to switch workspaces or even shut down and restart Finsemble without losing any work. When a component loads, you can have Finsemble retrieve the stored component state so that users can return to the app exactly where they left off.
Finsemble doesn’t store component states automatically. If you want to use a component state, you need to save it yourself.
If a workspace has multiple instances of a specific app, each instance of that app has its own separate component state.
Storing component state
Here is an example of storing a component layout:
let s = stx.exportLayout(true);
//saving layout'
FSBL.Clients.WindowClient.setComponentState({
field: "myChartLayout",
value: s,
});
FSBL.Clients.WindowClient.setComponentState({
fields: [
{ field: "myChartLayout", value: s },
{ field: "chartType", value: "mountain" },
],
});
Fetching component state
Use this code to fetch a component's state:
FSBL.Clients.WindowClient.getComponentState(
{
field: "myChartLayout",
},
function (err, state) {
importLayout(state);
}
);
FSBL.Clients.WindowClient.getComponentState(
{
fields: ["myChartLayout", "chartType"],
},
function (err, state) {
let chartType = state["chartType"];
let myChartLayout = state["myChartLayout"];
}
);
Evergreen apps and component state
To allow your users to pick up where they left off in the last session, you must retrieve and use the component state when your app starts on the Finsemble ready or connected events. An evergreen app is different because it can participate in multiple workspaces, and each of these workspaces can have multiple component states. For this reason you must not only fetch and use the component state when the app starts but also when the component-state-change event is triggered:
finsembleWindow.addEventListener("component-state-changed", (event) => {
// Update your app to use the new component state
console.log(event.data)
})