Windows

Layouts

JavaScript

Global Layouts

Global saving and restoring is an operation in which all applications running on the desktop are saved to a named layout which can later be restored.

The Layouts API can be accessed through glue.layouts.

Listing Layouts

If you want a snapshot of all layouts currently available, you can use:

glue.layouts.list() // returns an array of layout objects

Current Layout

To get the currently restored global layout, use the glue.layouts.getCurrentLayout() method:

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

Saving a Layout

To save a global layout, use glue.layouts.save() passing a configuration object with a required name property. Note that if a layout with that name already exists, it will be replaced. The resolved Promise includes the saved layout information, which can then be used or manipulated.

 glue.layouts.save({ name: layoutName })
    .then((layoutInfo) => {
        // handle the saved layout info
    })
    .catch((error) => {
        console.log(`Error saving layout: ${error}`)
    });

Restoring a Layout

To restore a global layout, use glue.layouts.restore() passing the name of the global layout:

 glue.layouts.restore({
    name: name,
    closeAllRunning: true
})
    .catch((error) => {
        console.log(`Error restoring layout: ${error}`)
    });

Removing Layouts

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

glue.layouts.remove("Global", "MyLayout");

Layout Events

Your application can react to layout events, such as adding, removing, updating or renaming a layout.

To subscribe for the event which fires when a layout is added, use the glue.layouts.onAdded() method. It returns an unsubscribe function which you can use 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 glue.layouts.onRemoved() method. It returns an unsubscribe function which you can use 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 glue.layouts.onChanged() method. It returns an unsubscribe function which you can use 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 glue.layouts.onRenamed() method. It returns an unsubscribe function which you can use to stop receiving notifications about the event.

glue.layouts.onRenamed(console.log): () => void;

Exporting Layouts

You can export all layouts for the current user with the glue.layouts.export() method. Here are some use cases for exporting layouts:

  • exported layouts can be stored to a database and then be used as restore points (if the user for some reason wants to);
  • exported layouts can be sent to another user and imported on their machine;

Example:

glue.layouts.export().then((layouts) => db.store);

Exporting is different from using the glue.layouts.list() method, as it does not return application default layouts, but all layouts in the system.

Importing Layouts

To import exported layouts, use the glue.layouts.import() method:

const mode = "replace";
glue.layouts.import(layouts, mode);

The ImportMode controls import behavior. If the mode is replace (the default value), all existing layouts will be removed. If it is merge, the layouts will be imported over the existing layouts.

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 default global layout, use the glue.layouts.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 glue.layouts.setDefaultGlobal() method:

glue.layouts.setDefaultGlobal("MyLayout");

To clear the default global layout, use the glue.layouts.clearDefaultGlobal() method:

glue.layouts.clearDefaultGlobal();

Activity Layouts

An activity layout is the saved layout of a running activity that can later be restored:

  • as a new activity instance - in this case, the restored activity will appear at the exact position the layout was saved;
  • or joined to an existing activity instance - in this case, the layout will be arranged around the owner window of the existing activity;

To save an activity layout, use:

glue.layouts.save({ name: "MyActivityLayout", type: "Activity" })
    .then((layout) => {
        // handle saved layout
    });

To restore an activity layout (by name):

glue.layouts.restore({ name: "MyActivityLayout", type: "Activity" })
    .then((layout) => {
        // handle restored layout
    });

Saving Context Data

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.

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 activity, the owner window can store custom activity context (different from the current activity context). When restored, the activity will have the saved context.

To save context data, applications can subscribe for layout save requests. The callback passed as an argument will be invoked when a layout save is requested:

glue.layouts.onSaveRequested((saveContext) => {
    return {
        windowContext: { gridWidth: 420 }
    };
});

The callback should 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 and you can access it from there:

const windowContext = await glue.windows.my().getContext();
const gridWidth = windowContext.gridWidth;

You can also use the glue.layouts.updateAppContextInCurrent() method to update the context that will be saved for the current application in the currently loaded global layout. 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 };

glue.layouts.updateAppContextInCurrent(context);

Reference

Reference