@interopio/ng

Overview

The IO Connect Angular wrapper, @interopio/ng, aims to facilitate Angular developers in initializing the IO Connect JavaScript libraries and using IO Connect functionalities in their projects. The IO Connect Angular wrapper works both with the @interopio/browser library, if you are working on a IO Connect Browser project, and with the @glue42/desktop library, if you are working on a IO Connect Desktop project. The @interopio/ng package is a simple lightweight wrapper which makes initializing a IO Connect Client and consuming the IO Connect APIs easy and convenient. The examples below use the IO Connect Browser library.

Prerequisites

This package should be used only in Angular applications. If your app was created with the Angular CLI, then you don't need to take any additional steps. However, if you have manually created your app, then you need to make sure to install the peer dependencies of @interopio/ng:

"dependencies": {
    "@angular/common": "^9.1.3",
    "@angular/core": "^9.1.3",
    "rxjs": "^6.5.5",
    "tslib": "^1.10.0"
}

The example below assumes that your app was created with the Angular CLI. Install @interopio/ng and the IO Connect Browser library:

npm install --save @interopio/ng @interopio/browser

Library Features

The IO Connect Angular library exposes two important elements:

• IOConnectNg - an Angular module that initializes the IO Connect Browser library;
• IOConnectStore - an Angular service that gives access to the IO Connect Browser API;

IOConnectNg Module

The IOConnectNg module is responsible for initializing the IO Connect Browser library. You must import the IOConnectNg module once for the entire application - in the root module by using the forRoot() method. This methods accepts a settings object which has the following signature:

IOConnectNgSettings = {
    config?: IOConnectNgFactoryConfig;
    factory?: IOConnectNgFactory;
    holdInit?: boolean;
};

• config - Optional. A configuration object for the IO Connect factory function (for detailed configuration options, see the IO Connect Client: Overview section);
• factory - Optional. A IO Connect factory function. If you do not pass a factory function, the IO Connect Angular library will search for a factory function attached to the global window object (e.g., window.IOBrowser when using the IO Connect Browser library);
• holdInit - Optional. Toggles whether or not your app initialization should wait for the IO factory function to resolve. Defaults to true;

The initialization of the IO Connect Browser library is asynchronous and therefore can take anywhere between a few milliseconds and 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 is recommended that you set holdInit to false. This way, your app will not 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 IO Connect Browser library is ready.

• holdInit: true - If the IO Connect functionalities, however, are a critical part your project, then it is 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 IO Connect Browser library is available or not 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.

The example below shows how to initialize the IO Connect Browser library by passing a factory function and a custom configuration object:

import { IOConnectNg } from "@interopio/ng";
import IOBrowser from "@interopio/browser";

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        IOConnectNg.forRoot({ factory: IOBrowser, config: { extends: false } })
    ],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule { }

It is important to note that if the IO Connect initialization fails for any reason (invalid configuration, missing factory function, connection problems or initialization timeout), your app will still initialize.

IOConnectStore Service

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

Example of creating a IOConnectStore service:

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

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

The IOConnectStore service offers the following methods:

• this.ioStore.ready() - returns an Observable. If you subscribe to it, you will be notified when the IO Connect Browser library has been initialized. If the initialization fails, you will receive an object with an error property, otherwise the object will be empty. This is particularly useful if you set holdInit to false when initializing the library, because you need to make sure that the IO Connect library is ready for use before accessing any of its APIs;
• this.ioStore.initError - returns an initialization error object returned from the IO Connect factory function or undefined;
• this.ioStore.getIOConnect() - returns the IO Connect Browser API object. If needed, it is up to the developer to cast the returned object to the respective type (either Glue42.Glue or IOConnectBrowser.API depending on the used IO Connect JavaScript library);

You can now inject the service in the components that need it and access the IO Connect Browser API from the this.ioStore.getIOConnect() object. This gives you a decent level of encapsulation and control. If you prefer handling async actions with Observables, then this service is the perfect place to wrap the methods you want to use in Observables.

Usage

Below you can see some examples of initializing and using the IO Connect Angular library.

Initialization

Import the IOConnectNg module in the root module of your app and pass the factory function from @interopio/browser:

import { BrowserModule } from "@angular/platform-browser";
import { NgModule } from "@angular/core";

import { AppComponent } from "./app.component";
import { IOConnectNg } from "@interopio/ng";
import IOBrowser from "@interopio/web";

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        IOConnectNg.forRoot({ factory: IOBrowser })
    ],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule { }

Consuming IO Connect Browser APIs

Inject the IOConnectStore service in your component/service of choice in order to use the IO Connect Browser API. It is recommended that you create your own Angular service that injects the IOConnectStore and exposes only the functionality your app needs.

When initializing the IO Connect Browser library with the IOConnectNg module, you can use the holdInit property (see IOConnectNg Module) to configure the Angular framework to wait or not 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. Below are given examples and short explanations for both cases:

• holdInit: true

Creating the service:

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

@Injectable()
export class IOConnectService {

    constructor(private readonly ioStore: IOConnectStore) { }

    public get ioAvailable() {
        return !!this.ioStore.initError;
    }

    public registerMethod(name: string, callback: () => void): Promise<void> {
        if (!this.ioAvailable) {
            return Promise.reject("IO Connect was not initialized.");
        }
        return this.ioStore.getIOConnect().interop.register(name, callback);
    }
}

Using the service:

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

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

    constructor(private ioService: IOConnectService) { }

    public ngOnInit(): void {
        if (!this.ioService.ioAvailable) {
            // Тhere 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 Browser library. However, you do need to always check if there is an initialization error by using this.ioStore.initError. If the IO Connect factory functions rejects or throws an error, your app will not crash, but IO Connect will not be available and the value of initError 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 ioStore: IOConnectStore) { }

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

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

Using the service:

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

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

    constructor(private ioService: IOConnectService) { }

    public ngOnInit(): void {
        // Show the loader.
        this.ioService
            .ready()
            .subscribe((ioStatus) => {
                if (ioStatus.error) {
                    // Hide the loader.
                    // IO Connect is not 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 always check the error object like in the previous example.