Windows

Overview

The Layouts API is accessible through the io.layouts object.

Configuration

It is possible to configure the Layouts library by using the layouts property of the optional Config object passed during the initialization of the io.Connect JavaScript library. The Layouts library supports several modes of initialization. It can also be configured whether to auto save the context of individual windows and for which Layout types (Global, App Default, Workspace) to save it.

Below is an example of configuring the Layouts library:

const config = {
    layouts: {
        mode: "full",
        // Individual window context will be saved only when saving the specified types of Layouts.
        autoSaveWindowContext: ["Global", "Workspace"]
    }
};

const io = await IODesktop(config);

The different modes of the Layouts library restrict or enable certain functionalities. In "slim" mode, Layouts can't be manipulated (created, removed, renamed) and Layout events aren't available, but custom context data can still be saved. In "full" mode, all functionalities are available.

The layouts object has the following properties:

Property Type Description
mode "full" | "slim" | "fullWaitSnapshot" In "full" mode, all Layout functionalities are available. In "slim" mode, Layout events aren't tracked and Layouts can't be manipulated. The "fullWaitSnapshot" mode is the same as the "full" mode, except that the Layouts library will notify that it is ready a little later - when a snapshot of the available Layouts has been received.
autoSaveWindowContext boolean | LayoutType[] If true, window context will be saved for all Layout types. If an array of Layout types is passed instead, window context will be saved only for the specified Layout types. Possible Layout types are "Global", "ApplicationDefault" and "Workspace".

Layout Operations

Current Global Layout

To get the currently restored Global Layout, use the getCurrentLayout() method:

const currentLayout = await io.layouts.getCurrentLayout();

Listing All Layouts

To get a collection of all currently available Layout objects, use the list() method:

const layouts = io.layouts.list();

The list() method isn't available in "slim" mode. Use export() instead.

All Layouts by Type

To get all Layouts by type, use the getAll() method and pass a LayoutType. It returns a collection of LayoutSummary objects, which don't contain the extensive objects describing the actual Layout components:

const allGlobalLayouts = await io.layouts.getAll("Global");

Specific Layout

To get a specific Layout, use the get() method and provide the name of the Layout and the LayoutType as arguments. Returns the requested Layout object or undefined if a Layout with the specified name and type doesn't exist:

const name = "My Layout";
const type = "Global";

const myLayout = await io.layouts.get(name, type);

Save

To save a Layout, use the save() method and pass a NewLayoutOptions object with a required name property. If a Layout with that name already exists, it will be replaced. This method returns the saved Layout object:

const options = {
    name: "My Layout"
};

const savedLayout = await io.layouts.save(options);

Available since io.Connect Desktop 9.1

When saving a Layout, you can specify whether to set it as the currently active Global Layout by using the setAsCurrent property of the NewLayoutOptions object:

const options = {
    name: "My Layout",
    setAsCurrent: true
};

const myLayout = await io.layouts.save(options);

Restore

To restore a Layout, use the restore() method and pass a RestoreOptions object specifying the name of the Layout (required) and other restore options:

const restoreOptions = {
    name: "My Layout",
    // Specify whether to close all running apps before restoring the Layout.
    // The default is `true` for Global Layouts.
    closeRunningInstance: false
};

await io.layouts.restore(restoreOptions);

Remove

To remove a Layout, use the remove() method. You must pass the LayoutType and the name of the Layout as arguments:

await io.layouts.remove("Global", "My Layout");

Export & Import

You can export all currently available Layout objects with the export() method. Exported Layouts can be stored to a database and then be used as restore points, or can be sent to another user and imported on their machine.

const layouts = await io.layouts.export();

The export() method (as opposed to list()) is available in all modes if you need to get a collection of all Layouts.

To import exported Layouts, use the import() method. Pass the collection of Layout objects to import and specify an ImportMode:

const mode = "merge";

await io.layouts.import(layouts, mode);

The ImportMode controls the import behavior. If set to "replace" (default), all existing Layouts will be removed. If set to "merge", the Layouts will be imported and merged with the existing Layouts.

Refresh

To force a refresh of the Layout list available to the user when using a REST service or io.Manager as a Layout store, use the forceRefresh() method:

await io.layouts.forceRefresh();

Layout Events

The Layouts API allows your app to react to Layout events - adding, removing, updating or renaming a Layout. Use the returned unsubscribe function to stop receiving notifications about the respective event.

Added

To subscribe for the event which fires when a Layout is added, use the onAdded() method:

io.layouts.onAdded(console.log);

Removed

To subscribe for the event which fires when a Layout is removed, use the onRemoved() method:

io.layouts.onRemoved(console.log);

Changed

To subscribe for the event which fires when a Layout is changed, use the onChanged() method:

io.layouts.onChanged(console.log);

Renamed

To subscribe for the event which fires when a Layout is renamed, use the onRenamed() method:

io.layouts.onRenamed(console.log);

Save & Update Context

When a Layout is saved, apps can store context data in it. When the Layout is restored, the context data is also restored and returned to the apps. Context data can be saved in all Layout types.

⚠️ Note that saving large volumes of custom data as window context (e.g., thousands of lines of table data) can lead to significant delays when saving a Layout. A Layout usually contains several (in some cases - many) apps and/or Workspaces (which can also contain many apps) and if one or more of the apps saves large amounts of context data each time a Layout is saved, this will significantly slow down the saving process. The methods for saving custom context work best with smaller amounts of data. If your app needs to save large amounts of data, you have to think about how to design this process better - for instance, you may store IDs, indices, etc., as context data, save the actual data to a database and when you restore the Layout, fetch the data using the data IDs saved as window context.

Saving Context Data

To save context data, apps can subscribe for Layout save requests using the onSaveRequested() method. A Layout save request event is fired when the user attempts to save a Layout or close a window, Workspace, etc. The on onSaveRequested() method accepts a callback which will be invoked when a Layout save request is triggered. The callback will receive as an argument a SaveRequestContext object containing the Layout name, type and context. Use it to determine the type of the Layout and instruct your app to react accordingly:

const saveRequestHandler = (requestInfo) => {
    // Get the Layout type.
    const layoutType = requestInfo.layoutType;

    // Return different context data depending on the Layout type.
    if (layoutType === "ApplicationDefault") {
        return { windowContext: { gridWidth: 42 } };

    } else if (layoutType === "Global") {
        return { windowContext: { gridWidth: 420 } };

    } else {
        // Return if not interested in other Layout types.
        return;
    };
};

io.layouts.onSaveRequested(saveRequestHandler);

The callback must return a SaveRequestResponse object that has a windowContext property.

After the Layout has been restored, the saved context data will be available in the window context:

// Extracting previously saved data from the window context.
const windowContext = await io.windows.my().getContext();
const gridWidth = windowContext.gridWidth;

Updating App Default Context

To manually update the context of the current window in its App Default Layout, use the updateDefaultContext() method:

const context = { io: 42 };

await io.layouts.updateDefaultContext(context);

Updating Context of Apps in Global Layouts

To update the context that will be saved for the current app in the currently loaded Global Layout, use the updateAppContextInCurrent() method. This method allows you to update the saved context for the current app in the Layout without having to save the entire Layout:

const context = { io: 42 };

await io.layouts.updateAppContextInCurrent(context);

Default Global Layout

io.Connect Desktop allows you to specify a default Global Layout that will be automatically loaded on start. You can get, set and clear the default Global Layout programmatically.

To get the current default Global Layout, use the getDefaultGlobal() method:

// May return `undefined` if no default Global Layout has been set.
const defaultLayout = await io.layouts.getDefaultGlobal();

To set a default Global Layout, use the setDefaultGlobal() method:

io.layouts.setDefaultGlobal("My Layout");

To clear the default Global Layout, use the clearDefaultGlobal() method:

io.layouts.clearDefaultGlobal();

Reference

For a complete list of the available Layouts API methods and properties, see the Layouts API Reference Documentation.