Modals

Available since io.Connect Browser 4.0

The @interopio/modals-api and @interopio/modals-ui libraries enable you to use modal windows (alerts and dialogs) in your io.Connect Browser projects.

The @interopio/modals-api library provides a convenient API for displaying and manipulating modal windows. You can use the Modals API with the default alert and dialog templates available via the @interopio/modals-ui library, as well as with your own custom modal windows.

The @interopio/modals-ui library provides the UI for the modal windows - a set of predefined alerts and dialog templates which you can use in your apps by simply configuring their content.

io.Connect Browser allows you to replace the default alerts and dialogs with your own custom modal windows by decorating the @interopio/modals-ui library or by creating an entirely new library that implements the @interopio/modals-ui API.

To be able to use the Modals API in your interop-enabled apps, install the @interopio/modals-api library in your project and reference it in your app. Depending on whether you want to use the Modals API in your Main app, or in a Browser Client app, see the respective initialization examples in the following sections.

⚠️ Note that enabling the Modals API and configuring the modal windows is required if you are using the Home App to build your io.Connect Browser project. Modal windows are necessary for the Launchpad to function properly.

To use the default io.Connect modal windows in your io.Connect Browser project, you must:

• Install the @interopio/modals-api library in your Main app and initialize it.

• Configure the io.Connect modal windows in the Main app - provide URLs pointing to the locations of the bundle, styles, and fonts for the modal windows, block any origins from using modal windows. You can use the default bundles, styles, and fonts provided by the @interopio/modals-ui library.

• Explicitly enable or disable using alerts and dialogs in the configuration object for the internal initialization of the @interopio/browser library in the Main app.

Install the necessary packages:

npm install @interopio/browser-platform @interopio/modals-api

Use the modals property of the configuration object for initializing the @interopio/browser-platform library to define the sources of the modal windows to be used by the platform. Enable the Modals API by passing the IOModals() factory function to the libraries array of the browser object used for the internal initialization of the @interopio/browser library:

import IOBrowserPlatform from "@interopio/browser-platform";
import IOModals from "@interopio/modals-api";

const config = {
    licenseKey: "my-license-key",
    // Settings for the modal windows to be used in the platform.
    modals: {
        sources: {
            // It's required to specify the locations of the bundle and styles for the modal windows.
            // You can use the resources provided by the `@interopio/modals-ui` library
            // or provide your own custom library that implements the `@interopio/modals-ui` API.
            bundle: "https://my-modals/modals-bundle.js",
            styles: ["https://my-modals/styles.css", "https://example.com/custom-styles.css"],
            // It's required to specify the fonts when using the default modal windows
            // provided by the `@interopio/modals-ui` library.
            fonts: ["https://my-modals/fonts.css"]
        }
    },
    browser: {
        // Enabling the Modals API.
        libraries: [IOModals],
        // Enabling the Main app to use modal windows.
        modals: {
            alerts: {
                enabled: true
            },
            dialogs: {
                enabled: true
            }
        }
    }
};

const { io } = await IOBrowserPlatform(config);

// Now you can access the Modals API via `io.modals`.

The modals object has the following properties:

The sources object has the following properties:

To enable the Modals API in your Browser Client apps, install the @interopio/browser and @interopio/modals-api libraries and initialize the @interopio/browser library by passing the IOModals() factory function in the configuration object. You must also explicitly enable or disable using alerts and dialogs in the Browser Client. When IOBrowser() resolves, the Modals API will be accessible via the modals property of the returned object - e.g., io.modals. The following examples demonstrate how to enable the Modals API in JavaScript, React, and Angular apps.

JavaScript

Install the necessary packages:

npm install @interopio/browser @interopio/modals-api

Initialize the @interopio/browser library enabling the Modals API:

import IOBrowser from "@interopio/desktop";
import IOModals from "@interopio/modals-api";

// Initializing the Modals API.
const config = {
    libraries: [IOModals],
    // Enabling the Browser Client to use modal windows.
    modals: {
        alerts: {
            enabled: true
        },
        dialogs: {
            enabled: true
        }
    }
};

const io = await IOBrowser(config);

// Now you can access the Modals API via `io.modals`.

By default, the IOBrowser() and IOModals() factory functions are injected in the global window object.

React

Install the necessary packages:

npm install @interopio/react-hooks @interopio/modals-api

Initialize io.Connect in one of the following ways:

• using the <IOConnectProvider /> component:

import { createRoot } from "react-dom/client";
import IOBrowser from "@interopio/browser";
import IOModals from "@interopio/modals-api";
import { IOConnectProvider } from "@interopio/react-hooks";

const settings = {
    browser: {
        factory: IOBrowser,
        config: {
            libraries: [IOModals],
            // Enabling the Browser Client to use modal windows.
            modals: {
                alerts: {
                    enabled: true
                },
                dialogs: {
                    enabled: true
                }
            }
        }
    }
};

const domElement = document.getElementById("root");
const root = createRoot(domElement);

root.render(
    <IOConnectProvider fallback={<h2>Loading...</h2>} settings={settings}>
        <App />
    </IOConnectProvider>
);

• using the useIOConnectInit() hook:

import IOBrowser from "@interopio/browser";
import IOModals from "@interopio/modals-api";
import { useIOConnectInit } from "@interopio/react-hooks";

const App = () => {
    const settings = {
        browser: {
            factory: IOBrowser,
            config: {
                libraries: [IOModals],
                // Enabling the Browser Client to use modal windows.
                modals: {
                    alerts: {
                        enabled: true
                    },
                    dialogs: {
                        enabled: true
                    }
                }
            }
        }
    };

    const io = useIOConnectInit(settings);

    return io ? <Main io={io} /> : <Loader />;
};

export default App;

Angular

Install the necessary packages:

npm install @interopio/ng @interopio/modals-api

Pass the IOModals() factory function to IOBrowser() using the config object:

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/browser";
import IOModals from "@interopio/modals-api";

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        IOConnectNg.forRoot({
            browser: {
                factory: IOBrowser,
                config: {
                    libraries: [IOModals],
                    // Enabling the Browser Client to use modal windows.
                    modals: {
                        alerts: {
                            enabled: true
                        },
                        dialogs: {
                            enabled: true
                        }
                    }
                }
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
});

export class AppModule { };

To use your own custom alerts and dialogs, you can either decorate the @interopio/modals-ui library or create your own modal windows library that implements the @interopio/modals-ui API.

⚠️ Note that in order for the io.Connect platform to be able to use a custom library for displaying modal windows, it's required for this custom library to implement the @interopio/modals-ui API. The structure of the @interopio/modals-ui API is described in the modals.ui.d.ts file distributed with the library.

After decorating the @interopio/modals-ui library or implementing your custom modal windows, you must create and export a custom factory function and attach it to the global window object as IOBrowserModalsUI(). The factory function accepts as a first required argument the io.Connect API object returned from initializing the @interopio/browser library. As a second required argument, it accepts a configuration object for the @interopio/modals-ui library.

The following example demonstrates how to create your custom factory function and attach it to the global window object:

import IOBrowserModalsUI from "@interopio/modals-ui";

// Define your custom factory function that accepts the initialized io.Connect API object
// and a configuration object for the `@interopio/modals-ui` library.
const MyCustomIOBrowserModalsUI = async (io, config) => {

    // Decorate the `@interopio/modals-ui` library or create your own custom modal windows
    // library that implements the `@interopio/modals-ui` API.

    // Return the invocation of the default factory function if you want to decorate the library.
    return IOBrowserModalsUI(io, config);
};

if (typeof window !== "undefined") {
    // Inject your custom factory function in the global `window` object as `IOBrowserModalsUI`.
    window.IOBrowserModalsUI = MyCustomIOBrowserModalsUI;
};

export default MyCustomIOBrowserModalsUI;

To instruct the io.Connect platform to use your custom modal windows library, use the sources property of the modals top-level key in the configuration object for initializing the @interopio/browser-platform library to provide URLs pointing to the locations of your custom library bundle and styles:

import IOBrowserPlatform from "@interopio/browser-platform";
import IOModals from "@interopio/modals-api";

const config = {
    licenseKey: "my-license-key",
    modals: {
        sources: {
            // Provide the locations of your custom library bundle and styles.
            bundle: "https://my-modals/my-custom-bundle.js",
            styles: ["https://my-modals/my-custom-styles.css"]
        }
    },
    browser: {
        // Enabling the Modals API.
        libraries: [IOModals],
        // Enabling the Main app to use modal windows.
        modals: {
            alerts: {
                enabled: true
            },
            dialogs: {
                enabled: true
            }
        }
    }
};

const { io } = await IOBrowserPlatform(config);

To customize the styles of the io.Connect modal windows, use the dedicated CSS variables provided by the io.Connect themes.