How to...

The @interopio/ng library provides functions, modules, and services for the io.Connect JavaScript libraries - @interopio/browser and @interopio/browser-platform, if you are working on an io.Connect Browser project, or @interopio/desktop, if you are working on an io.Connect Desktop project.

The following examples use the @interopio/desktop library. The @interopio/ng library enables you to start using io.Connect features in your Angular apps idiomatically in the context of the Angular framework.

The following table describes the Angular versions supported by the different major versions of the @interopio/ng library:

This package should be used only in Angular apps. If you have created your app with the Angular CLI, then you don't need to take any additional steps. Otherwise, make sure to install the peer dependencies of @interopio/ng described in the package.json file of the library.

The following example assumes that your app was created with the Angular CLI. To install the @interopio/ng library, execute the following command:

npm install @interopio/ng

The @interopio/ng library exposes the following important features:

⚠️ Note that if the initialization of the @interopio/ng library fails for any reason (invalid configuration, missing factory function, connection problems, or initialization timeout), your app will still initialize.

Settings

The provideIoConnect() function and the forRoot() method of the IOConnectNg module accept an IOConnectNgSettings object for initializing the @interopio/ng library.

The IOConnectNgSettings object has the following signature:

interface IOConnectNgSettings {
    holdInit?: boolean;
    browser?: {
        factory?: IOConnectBrowserFactoryFunction;
        config?: IOConnectBrowser.Config;
    };
    browserPlatform?: {
        factory?: IOConnectBrowserPlatformFactoryFunction;
        config?: IOConnectBrowserPlatform.Config;
    };
    desktop?: {
        factory?: IODesktopFactoryFunction;
        config?: IOConnectDesktop.Config;
    };
}

The following table describes the properties of the IOConnectNgSettings object:

⚠️ Note that you can't define a browser and browserPlatform property at the same time, but you can define one of them together with desktop. This is useful if you want your app to have different initialization characteristics in io.Connect Browser and io.Connect Desktop.

All properties are optional, but it's recommended that you provide the factory functions explicitly. If no factory functions are provided, the library will try to select the appropriate function injected in the global window object.

The initialization of the @interopio/ng library is asynchronous and therefore may take anywhere from a few milliseconds to a couple of seconds. There are two main situations in which setting holdInit to true (default) or false will benefit your project:

• holdInit: false - If the io.Connect functionalities play only a supporting role in your project, rather than being an essential part of it, it's recommended that you set holdInit to false. This way, your app won't have to wait for the io.Connect library to initialize in order to be able to function properly. You can use the IOConnectStore service to get notified when the @interopio/ng library is ready.

• holdInit: true - If the io.Connect functionalities are a critical part your project, then it's recommended to leave holdInit set to true. This way, Angular will wait for the io.Connect factory function to resolve before bootstrapping your first component. This will spare you the need to check whether the @interopio/ng library is available every time you want to use it in your app. As a negative result to this approach, when your users load the app, they will keep seeing a blank screen up until the first component has been bootstrapped. Of course, you can solve this by providing a loader animation as soon as your app is accessed.

provideIoConnect()

The provideIoConnect() function is responsible initializing the @interopio/ng library when using standalone components. You must use the provideIoConnect() function in the app.config.ts file of your app. The provideIoConnect() function accepts an IOConnectNgSettings object for configuring the library.

The following example demonstrates how to initialize the @interopio/ng library when using standalone components:

import { ApplicationConfig } from "@angular/core";
import { provideIoConnect } from "@interopio/ng";
import IODesktop, { IOConnectDesktop } from "@interopio/desktop";

const config: IOConnectDesktop.Config = {
    // Optional configuration.
};

export const appConfig: ApplicationConfig = {
    providers: [
        // Configuring and initializing the io.Connect Desktop library.
        provideIoConnect({
            desktop: {
                factory: IODesktop,
                config
            }
        })
    ]
};

IOConnectNg Module

The IOConnectNg module is responsible for initializing the @interopio/ng library when using modules. You must import the IOConnectNg module only once for the entire app in the root module by using the forRoot() method. The forRoot() method accepts an IOConnectNgSettings object for configuring the library.

The following example demonstrates how to initialize the @interopio/ng library when using modules:

import { IOConnectNg } from "@interopio/ng";
import IODesktop from "@interopio/desktop";

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        IOConnectNg.forRoot({
            desktop: {
                factory: IODesktop
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
});

export class AppModule { };

IOConnectStore Service

The IOConnectStore service is used to obtain the io object which exposes the io.Connect API. This service can also notify you when the @interopio/ng library has been initialized and enables you to check for any initialization errors.

Example of creating an IOConnectStore service:

import { Injectable } from "@angular/core";
import { IOConnectStore } from "@interopio/ng";

@Injectable()
export class IOConnectService {
    constructor(private readonly ioConnectStore: IOConnectStore) { }
}

The IOConnectStore service offers the following methods:

You can inject the service in the components that need it and access the io.Connect API from the object returned by getIOConnect(). If you prefer handling asynchronous actions with Observables, then this service is the perfect place to wrap the methods you want to use in Observables.

The following examples demonstrate initializing and using the @interopio/ng library.

Initialization

Standalone Components

In app.config.ts:

import { ApplicationConfig } from "@angular/core";
import { provideIoConnect } from "@interopio/ng";
import IODesktop, { IOConnectDesktop } from "@interopio/desktop";

const config: IOConnectDesktop.Config = {
    // Optional configuration.
};

export const appConfig: ApplicationConfig = {
    providers: [
        // Configuring and initializing the io.Connect Desktop library.
        provideIoConnect({
            desktop: {
                factory: IODesktop,
                config
            }
        })
    ]
};

In main.ts:

import { bootstrapApplication } from "@angular/platform-browser";
import { appConfig } from "./app/app.config";
import { App } from "./app/app";

bootstrapApplication(App, appConfig);

Modules

The following example demonstrates initializing the @interopio/ng library in apps that use Angular versions 15 and later.

In app.config.ts:

import { ApplicationConfig, importProvidersFrom } from "@angular/core";
import { IOConnectNg } from "@interopio/ng";
import IODesktop, { IOConnectDesktop } from "@interopio/desktop";

const config: IOConnectDesktop.Config = {
    // Optional configuration.
};

export const appConfig: ApplicationConfig = {
    providers: [
        importProvidersFrom(
            IOConnectNg.forRoot({
                desktop: {
                    factory: IODesktop,
                    config
                }
            })
        )
    ]
};

The following example demonstrates initializing the @interopio/ng library in apps that use Angular versions 14 and older.

In app.module.ts:

import { NgModule } from "@angular/core";
import { AppComponent } from "./app.component";
import { IOConnectNg } from "@interopio/ng";
import IODesktop, { IOConnectDesktop } from "@interopio/desktop";

const config: IOConnectDesktop.Config = {
    // Optional configuration.
};

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        IOConnectNg.forRoot({
            desktop: {
                factory: IODesktop,
                config
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
});

export class AppModule { };

Consuming io.Connect APIs

Inject the IOConnectStore service in your component or service of choice in order to use the io.Connect API. It's recommended that you create your own Angular service that injects IOConnectStore and exposes only the functionality your app needs.

When initializing the @interopio/ng library, you can use the holdInit property to configure whether the Angular framework must wait for the io.Connect factory function to resolve before bootstrapping your first component. Depending on this setting, you can use the IOConnectStore service in different ways. The following sections demonstrate both cases.

• holdInit: true

Creating the service:

import { Injectable } from "@angular/core";
import { IOConnectStore } from "@interopio/ng";

@Injectable()
export class IOConnectService {

    constructor(private readonly ioConnectStore: IOConnectStore) { }

    public get ioConnectAvailable() {
        return !this.ioConnectStore.getInitError();
    }

    public registerMethod(name: string, callback: () => void): Promise<void> {
        if (!this.ioConnectAvailable) {
            return Promise.reject("io.Connect wasn't initialized.");
        }
        return this.ioConnectStore.getIOConnect().interop.register(name, callback);
    }
}

Using the service:

import { Component, OnInit } from "@angular/core";
import { IOConnectService } from "./my-io-connect-service";

@Component({
    selector: "app-root",
    templateUrl: "./app.component.html",
    styleUrls: ["./app.component.css"]
})
export class AppComponent implements OnInit {

    constructor(private ioConnectService: IOConnectService) { }

    public ngOnInit(): void {
        if (!this.ioConnectService.ioConnectAvailable) {
            // There has been an error during the io.Connect initialization.
            return;
        }
        // io.Connect has been initialized without errors and is ready to use.
    }
}

If you set holdInit to true (default), you can be sure that everywhere you inject the IOConnectStore service, the respective properties will be initialized and set. This is very convenient, because you don't have to subscribe and wait for an event in order to use the io.Connect APIs. However, you do need to always check if there is an initialization error by using the getInitError() method. If the io.Connect factory function throws an error, your app won't crash, but io.Connect won't be available and the value returned by getInitError() will be set to the respective error object during initialization.

• holdInit: false

Creating the service:

import { Injectable } from "@angular/core";
import { IOConnectStore } from "@interopio/ng";

@Injectable()
export class IOConnectService {

    constructor(private readonly ioConnectStore: IOConnectStore) { }

    public ready() {
        return this.ioConnectStore.ready;
    }

    public registerMethod(name: string, callback: () => void): Promise<void> {
        return this.ioConnectStore.getIOConnect().interop.register(name, callback);
    }
}

Using the service:

import { Component, OnInit } from "@angular/core";
import { IOConnectService } from "./my-io-connect-service";

@Component({
    selector: "app-root",
    templateUrl: "./app.component.html",
    styleUrls: ["./app.component.css"]
})
export class AppComponent implements OnInit {

    constructor(private ioConnectService: IOConnectService) { }

    public ngOnInit(): void {
        // Show the loader.
        this.ioConnectService
            .ready()
            .subscribe((ioConnectStatus) => {
                if (ioConnectStatus.error) {
                    // Hide the loader.
                    // io.Connect isn't available.
                    return;
                }
                // Hide the loader.
                // io.Connect is ready, continue with your logic.
            })
    }
}

As you can see, this approach requires a little bit more code, but it gives you an easy way to provide pleasant user experience while io.Connect is initializing, handle gracefully any initialization errors, and when the initialization resolves normally, you don't need to check the error object as in the previous example.

To add your Angular app to the io.Connect launcher, you must create a JSON app definition file for it. Place this file in the <installation_location>/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 Angular app:

{
    "name": "my-app",
    "title": "My App",
    "type": "window",
    "details": {
        "url": "https://example.com/my-app/",
        "mode": "tab",
        "width": 500,
        "height": 400
    }
}

The "name", "type", and "url" properties are required and "type" must be set to "window". The "url" property points to the location of the web app.

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 if the web app doesn't have a document title.

ℹ️ For more details on defining apps, see the Developers > Configuration > Application section.

Once the @interopio/ng 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 the following sections:

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

For a complete list of the available JavaScript APIs, see the io.Connect JavaScript reference documentation.