Windows

End users in large enterprises often have multi-monitor setups on which they arrange the necessary apps in the most convenient way for executing daily tasks. The io.Connect Browser Layouts feature allows them to save and later restore the exact arrangement and context of their environment - windows, apps, Workspaces, and their bounds and context. Users can save multiple apps and Workspaces in different Layouts, each corresponding to a specific task or workflow. Restoring the saved Layout happens with a single click and saves time and effort for finding, launching and arranging the desired apps.

The Layouts library has the following capabilities:

• importing, exporting, removing and getting Layouts;
• saving and restoring Layouts (exclusive to io.Connect Browser);
• events related to adding, removing, changing or saving Layouts;
• requesting permission for the browser Window Management API;

The io.Connect Browser Layouts library supports different types of Layouts:

• Global

This type of Layout can contain floating windows, apps and Workspaces. A Global Layout describes the bounds and context of all components participating in it.

⚠️ Note that the Main app isn't saved in a Global Layout, as it's assumed that the Main app is the entry point of an io.Connect Browser project from where all Global Layouts are to be handled.

• Workspace

The Layout of a Workspace instance describes the arrangement of the Workspace elements, its bounds and the context of the apps participating in it.

To provide configuration for the Layouts library, use the layouts property of the configuration object when initializing the @interopio/browser-platform library. The following example demonstrates configuring the Layouts library and enabling the Workspaces API, so that Workspace Layouts can be restored too:

import IOBrowserPlatform from "@interopio/browser-platform";
import IOWorkspaces from "@interopio/workspaces-api";

const config = {
    licenseKey: "my-license-key",
    browser: {
        libraries: [IOWorkspaces]
    },
    workspaces: {
        src: "http://localhost:3000"
    },
    layouts: {
        mode: "session",
        // Layout definition objects.
        local: [ {...}, {...}]
    }
};

const { io } = await IOBrowserPlatform(config);

The layouts object has the following properties:

Property	Type	Description
mode	"session" | "idb"	Mode for storing Layouts. Use the "idb" setting if you want the Layouts to be persisted using the IndexedDB API of the browser. This option is useful for testing and PoC purposes, because it simulates persisting and manipulating Layouts on a server. The "session" setting means that the Layouts will be handled using the browser session storage. Once the browser session is over (e.g., the user closes the Main app window), all user-created Layouts will be lost. If the Main app is only refreshed, however, the Layouts will still be available.
local	object[]	Array of Layout objects. On startup, these predefined Layouts will be imported and merged with the already existing Layouts and the Layouts with the same names will be replaced. This ensures that the user-created Layouts won't be removed when in "idb" mode.

Enabling the Workspaces API isn't strictly required in order to use Global Layouts, but it's highly recommended, because you can never be completely sure what type of Layout your system will need to restore. If the Global Layout you want to restore describes one or more components which are Workspace Layouts, then a missing Workspaces configuration will result in errors.

Global Layouts in io.Connect Browser and in io.Connect Desktop are optimally, but not entirely compatible. When using the same Layouts in io.Connect Browser and in io.Connect Desktop, you have to consider the following:

• All Layouts saved in io.Connect Browser can be imported and restored in io.Connect Desktop, provided that the apps described in the Layout are also part of io.Connect Desktop.

• All Layouts saved in io.Connect Desktop can be imported and will be restored as accurately as possible in io.Connect Browser. This is due to the fact that io.Connect Desktop has advanced window management capabilities like support for different window types, advanced window tabs, native apps and much more, which can't be translated to a web Layout, because most of these features aren't available in the standard browsers, or in the case of window tabs, the browser tabbing significantly restricts and complicates the io.Connect Window Management capabilities. If an io.Connect Desktop Layout contains tabbed windows, in an io.Connect Browser Layout, they will be restored as separate browser windows with the same bounds on the screen. If an io.Connect Desktop Layout contains a native app participating in a Workspace, in an io.Connect Browser Layout, the Workspace will be restored with an empty component containing a "+" button in it from which the user can add a new app.

• When an io.Connect Desktop Layout is imported, restored and saved again in io.Connect Browser, only a soft update is performed on the original components of the Layout. This means that only the bounds and the context of the original components are updated. This preserves all properties specific to io.Connect Desktop.

• To ensure optimal control over how and what is saved and restored in a Layout, it's recommended to use the metadata property of a Layout object to indicate the target environment for the Layout. This will allow you to import and restore only the Layouts for the environment in which your app is currently running.

Browser Requirements

Global Layouts require that the browser supports the Window Management API, which was introduced in Chrome 100 and in Edge 100. If this API isn't available, Global Layouts won't be able to initialize, resulting in an error.

Window Management Permission

The Window Management API of the browser, required for using Global Layouts, in turn requires an explicit permission by the user. Requesting this permission must be done carefully and must be planned well, because should the user deny the permission, then there is no programmatic way to ask them again or revert their decision. That's why the Global Layouts library offers methods containing all necessary tools for the developer to ask the user for the Window Management permission at the right moment and in a well-designed way. For more details and examples, see the Layouts API > Requesting Window Management Permission and Layouts API > Checking the Global Layouts State sections.

⚠️ Note that if requesting this permission isn't handled with the provided methods, the Global Layouts library will automatically request it the first time a Layout is saved or restored, but this default behavior isn't recommended, as it isn't ideal for the user experience.

Non-io.Connect Windows and Apps

Not all of your windows and apps will use one of the io.Connect libraries and be interop-enabled. In such a situation, io.Connect Browser has limited options - programmatically moving, resizing and getting the current position of such windows isn't possible. In this case, all windows and apps that aren't interop-enabled will be saved in a Global Layout, but they will be restored with their initial bounds, no matter how the user has moved or resized them after loading the Layout.

Non-io.Connect windows and apps participating in a Workspace will be saved and restored just like any other interop-enabled window, because the Workspaces App controls the bounds of the components in which the windows are placed.

Window State

Current browsers don't allow for programmatic getting or changing the state of the window (minimized, maximized, normal). As a result, all components in a saved Global Layout in io.Connect Browser will be set to window state "normal". Windows that are manually maximized by the user will be saved and restored to fit the entire window, but won't be maximized. Windows that are minimized by the user will be saved and restored in a normal state.