Windows

Layouts

JavaScript

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 Glue42 JavaScript library. The Layouts library supports several modes of initialization and can also be configured whether to auto save the context of individual windows in their Application Default layout.

Below is an example configuration of the Layouts library:

const config = {
    layouts: {
        mode: "full",
        autoSaveWindowContext: true
    }
};

window.glue = await Glue(config);

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

Layout Types

The Layouts library supports several types of layouts - Global, Application Default, Activity, Swimlane and Workspace. To check the type of the layout, use the type property of the Layout object:

// Get all available layouts.
const allLayouts = glue.layouts.list();

// Get all Global layouts.
const globalLayouts = allLayouts.filter(layout => layout.type === "Global");

Layout Operations

The Layouts API can be accessed through glue.layouts.

Current Global Layout

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

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

Listing

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

const layouts = glue.layouts.list(); 

The list() method is not available in "slim" mode. Use export() instead.

Saving and Restoring

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

const layoutConfig = { 
    name: "My Layout",
    // Optionally specify a layout type. The default is "Global".
    type: "Workspace"
};

const savedLayout = await glue.layouts.save(layoutConfig).catch(console.error);

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 glue.layouts.restore(restoreOptions);

Removing

To remove a layout, use the remove() method. You must pass the type of the layout and its name:

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

Exporting and Importing

You can export all currently available layouts with the export() method. Exported layouts can be stored to a database and then be used as restore points (if the user for some reason wants to), or can be sent to another user and imported on their machine.

const layouts = await glue.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 layout collection to import and specify an import mode:

const mode = "merge";

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

Layout Events

The Layouts API allows your application to react to layout events - adding, removing, updating or renaming a layout.

To subscribe for the event which fires when a layout is added, use the onAdded() method. Use the returned unsubscribe function to stop receiving notifications about the event.

glue.layouts.onAdded(console.log);

To subscribe for the event which fires when a layout is removed, use the onRemoved() method. Use the returned unsubscribe function to stop receiving notifications about the event.

glue.layouts.onRemoved(console.log);

To subscribe for the event which fires when a layout is changed, use the onChanged() method. Use the returned unsubscribe function to stop receiving notifications about the event.

glue.layouts.onChanged(console.log);

To subscribe for the event which fires when a layout is renamed, use the onRenamed() method. Use the returned unsubscribe function to stop receiving notifications about the event.

glue.layouts.onRenamed(console.log);

Saving and Updating Context

When a layout is saved, applications can store context data in it. When the layout is restored, the context data is also restored and returned to the applications. Context data can be saved in all layout types - Global, Application Default, Activity, Swimlane, Workspace.

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) applications 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 application 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.

The context data can be one of two types:

  • Window context - each window (application) can store window specific context. When restored, the window will have the saved context;
  • Activity context - if running in an Activity, the owner window can store custom Activity context (different from the current Activity context). When restored, the Activity will have the saved context;

Saving Context Data

To save context data, applications 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 (e.g., Global, Workspace) or close a window, Activity, 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 application to react accordingly:

glue.layouts.onSaveRequested((requestInfo) => {
    // Determine 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;
    };
});

The callback must return a SaveRequestResponse object that has windowContext and/or activityContext properties.

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 glue.windows.my().getContext();
const gridWidth = windowContext.gridWidth;

Updating Application Default Context

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

const context = { glue: 42 };

await glue.layouts.updateDefaultContext(context);

Updating Context of Apps in Global Layouts

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

const context = { glue: 42 };

await glue.layouts.updateAppContextInCurrent(context);

Default Global Layout

Glue42 Enterprise 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 glue.layouts.getDefaultGlobal();

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

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

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

glue.layouts.clearDefaultGlobal();

Reference

Reference