How to...

All io.Connect JavaScript functionalities are available for your Electron apps through the io.Connect Electron library - @interopio/electron.

Your interop-enabled Electron apps can be defined as io.Connect apps (see App Definition) in order to be started by io.Connect Desktop, or they can run independently.

When initialized in your Electron app, the @interopio/electron library will discover any running instance of io.Connect and connect to it and will inject the io.Connect library in all windows of your app. Registering your main window as an io.Connect Window will enable it to stick to other io.Connect 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 io.Connect apps so that they can participate in io.Connect.

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

npm install @interopio/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 io object returned by a successful initialization is the entry point for all io.Connect APIs:

// Reference the io.Connect Electron library.
import * as glue42Electron from "@interopio/electron";

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

Configuration

The io.Connect 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 io = await glue42Electron.initialize(config);

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

Startup Options

When your Electron app is started by io.Connect Desktop, you can extract the app startup options from the io object returned by the initialized io.Connect Electron library:

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

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

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

The startup options object has the following properties:

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

For details on how to define your Electron app as an io.Connect app using configuration files, see the App Definition section.

Main Window

When your app is ready and the io.Connect 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 definition (if any).

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

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

// Register your main window.
const ioConnectMainWindow = await io.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 an io.Connect app so that it will be able to participate fully in io.Connect.

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 io.Connect 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 ioConnectWindow = await io.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 io.Connect 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 arguments. 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 io.Connect environment which is necessary for connecting to io.Connect:

// 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 io.registerAppFactory(appDefinition, factory);

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

To add your Electron app to the io.Connect launcher, you must create a JSON file with app definition. Place this file in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The following is an example definition of an Electron app:

{
    "title": "My Electron App",
    "type": "exe",
    "name": "my-electron-app",
    "details": {
        "path": "%GDDIR%/../Demos/MyElectronApp/",
        "command": "MyElectronApp.exe",
        "parameters": " --mode=1"
    }
}

The "name", "type" and "path" properties are required and "type" must be set to "exe". The "path" property points to the app working directory.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

For more details, see the Developers > Configuration > Application section.

See the Electron example on GitHub which demonstrates the various io.Connect Desktop features.

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

• App Management
• App Preferences
• Intents
• Shared Contexts
• Channels
• Interop
• Pub/Sub
• Window Management
• Workspaces
• Layouts
• Notifications
• Search
• Hotkeys
• Zooming
• Displays
• Logging

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