How to...

Overview

All Glue42 JavaScript functionalities are available for your Electron apps through the Glue42 Electron library - @glue42/electron.

Your Glue42 enabled Electron apps can be configured as Glue42 apps (see App Configuration) in order to be started by Glue42 Enterprise, or they can run independently.

When initialized in your Electron app, the @glue42/electron library will discover any running instance of Glue42 and connect to it and will inject the Glue42 library in all windows of your app. Registering your main window as a Glue42 Window will enable it to stick to other Glue42 Windows, use Channels and be saved and restored in Layouts. The library allows your app to register itself as an app factory for certain types of windows and also to register its own child windows as Glue42 apps so that they can participate in Glue42.

Referencing and Initialization

The @glue42/electron library is available as an NPM package. To install it, run the following command in the root directory of your project:

npm install @glue42/electron

Reference the library in your Electron app and use the initialize() method to initialize the library in the main process of your app, after the app "ready" event. The glue object returned by a successful initialization is the entry point for all Glue42 APIs:

// Reference the Glue42 Electron library.
import * as glue42Electron from "@glue42/electron";

// Initialize the library to access the Glue42 APIs.
const glue = await glue42Electron.initialize();

Configuration

The Glue42 Electron library can also be initialized with an optional configuration object:

// Provide optional configuration for your app.
const config = {
    appDefinition: {
        name: "my-electron-app",
        title: "My Electron App"
    }
};

const glue = await glue42Electron.initialize(config);

The configuration object has the following properties, all of which are optional:

Property Type Description
appDefinition object Runtime definition for an EXE app. For more details, see Application Configuration.
env string Glue42 Enterprise environment.
region string Glue42 Enterprise region.
gwURL string URL to the Glue42 Gateway to which to connect.
inject "glue" | "fdc3" | "none" By default, the Glue42 Electron library will inject the @glue42/desktop library in your Electron app windows. To inject the @glue42/fdc3 library instead, set to "fdc3". To disable injection, set to "none". Note that the libraries will be injected, but not initialized. If you want to inject a library, the preload property must be set to true.
preload boolean When true (default), a service object will be added to the list of preloads for each window. This object holds information which is necessary for connecting to Glue42. Set to false if you want to disable adding preloads to your windows - in this case, injection will be disabled and you will have to reference the Glue42 library in your windows in order to be able to use it. You will also have to provide the necessary information for connecting to Glue42. This information can be extracted from the Startup Options when the app is started by Glue42 Enterprise, or in the case of registering an app factory, you can use the service object that is passed as an argument to the factory function.

Startup Options

When your Electron app is started by Glue42 Enterprise, you can extract the app startup options from the glue object returned by the initialized Glue42 Electron library:

// Extracting the startup options.
const options = glue.startupOptions;

// Extracting the app starting context.
const context = options.context;

// Extracting the Glue42 Window settings.
const windowSettings = options.windowOptions;

The startup options object has the following properties:

Property Type Description
instanceId string Instance ID.
context object Startup context for the new app.
gwURL string URL to the Glue42 Gateway to which to connect.
gwToken string Token to be used as an authentication mechanism when connecting to the Glue42 Gateway.
applicationConfig object The app configuration as defined in the app store. See App Configuration.
env string The Glue42 Enterprise environment.
region string The Glue42 Enterprise region.
windowOptions object Glue42 Window settings.

Registering App Windows

The Glue42 Electron library allows you to register your Electron app windows in the Glue42 framework dynamically at runtime. This will enable them to stick to other Glue42 Windows, use Channels and be saved and restored in Layouts.

For details on how to configure your Electron app as a Glue42 app using configuration files, see the App Configuration section.

Main Window

When your app is ready and the Glue42 Electron library has been initialized, register your main window using the registerStartupWindow() method. Pass the main window as a required first argument and, optionally, pass a configuration object that will override the app configuration (if any).

The following example demonstrates how to register the main window, enable the Glue42 Channels and join the "Red" Channel:

// Optional configuration for your main window.
const config = {
    allowChannels: true,
    channelId: "Red"
};

// Register your main window.
const glue42MainWindow = await glue.registerStartupWindow(this.mainWindow, config);

Child Windows

Your Electron app may be able to create addition windows offering different functionalities to the user - e.g., a chat window that can be opened by clicking a button or a link in your main window. You can register this child window as a Glue42 app so that it will be able to participate fully in Glue42.

To register a child window, use the registerChildWindow() method. Pass a browser window and an app definition object as the first two required arguments and, optionally, specify Glue42 Window settings.

The following example demonstrates how to register a child window as a tab window and specify its bounds:

const bw = new BrowserWindow();

// Provide an app definition.
const appDefinition = {
    name: "my-child-electron-app",
    title: "My Child Electron App"
};

// Provide window options.
const options = {
    mode: "tab",
    left: 100,
    top: 100,
    width: 400,
    height: 400
};

// Register your child window.
const glue42Window = await glue.registerChildWindow(bw, appDefinition, options);

App Factories

You can register your Electron app as a factory for different types of windows. This will allow any other Glue42 app to create that window with a given context - e.g., open a chat window and pass relevant information to it.

To register an app factory, use the registerAppFactory() method which accepts an app definition and a factory function as required parameters. The factory function will be invoked with three arguments - the provided app definition, a context object (startup context or last saved context when restoring the window) and a service object that holds information about the current Glue42 environment which is necessary for connecting to Glue42:

// Provide an app definition.
const appDefinition = {
    name: "my-child-electron-app",
    title: "My Child Electron App"
};

// Provide a factory function for creating the app.
const factory = (appDefinition, context, glue42electron) => {

    // If you want to override window settings, use `this`.
    this.title = context.title;

    const bw = new BrowserWindow();

    // Must return the newly created browser window.
    return bw;
};

// Register the app factory.
await glue.registerAppFactory(appDefinition, factory);

Note that you can use the service object passed as a third argument to the factory function to properly initialize the Glue42 Electron library in your window in case you have disabled preloads. For more details, see the Configuration section.

App Configuration

To add your Electron app to the Glue42 Toolbar, you must create a JSON file with app configuration. Place this file in the %LocalAppData%\Tick42\UserData\<ENV-REG>\apps folder, where <ENV-REG> must be replaced with the environment and region of your Glue42 Enterprise copy (e.g., T42-DEMO).

The following is an example configuration for an Electron app:

{
    "title": "My Electron App",
    "type": "exe",
    "name": "my-electron-app",
    "icon": "https://example.com/icon.ico",
    "details": {
        "path": "%GDDIR%/../Demos/MyElectronApp/",
        "command": "MyElectronApp.exe",
        "parameters": " --mode=1"
    }
}
Property Description
"type" Must be "exe".
"path" The path to the app - relative or absolute. You can also use the %GDDIR% environment variable, which points to the Glue42 Enterprise installation folder.
"command" The actual command to execute (the EXE file name).
"parameters" Specifies command line arguments.

For more detailed information about the app definitions, see the Configuration documentation.

See the Electron example on GitHub which demonstrates the various Glue42 Enterprise features.

Glue42 JavaScript Concepts

Once the Glue42 Electron library has been initialized, your app has access to all Glue42 functionalities. For more detailed information on the different Glue42 concepts and APIs, see:

Reference

For a complete list of the available JavaScript APIs, see the Glue42 JavaScript Reference Documentation.