Windows

⚠️ Note that this feature is still experimental in io.Connect Desktop.

io.Connect Desktop supports a set of predefined modal windows (alerts and dialogs), which you can use in your interop-enabled apps via the @interopio/modals-api library. The Modals API also enables you to display your own custom alerts and dialogs.

⚠️ Note that you can also use the showDialog() method of an IOConnectWindow instance to show dialogs from your apps. This method is still supported and you can use it to show the already existing set of predefined dialogs, as well as custom ones, but it doesn't support the set of predefined dialogs available via the new @interopio/modals-api library. Respectively, the @interopio/modals-api library doesn't support the predefined dialogs available via the showDialog() method.

The following sections describe the available configuration settings for the io.Connect alerts and dialogs.

Alerts

Available since io.Connect Desktop 9.9

To provide settings for alert windows, use the "alerts" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "alerts": {
        "enabled": true,
        "width": 450,
        "height": 100,
        "ttl": 7000,
        "roundedCorners": true
    }
}

The "alerts" object has the following properties:

Dialogs

To provide settings for dialog windows, use the "dialogs" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "dialogs": {
        "url": "https://my-custom-dialog.com",
        "width": 380,
        "height": 150,
        "enableDefaultDialogs": {
            "preventShutdown": false,
            "preventWindowClose": false
        }
    }
}

The "dialogs" object has the following properties:

The "enableDefaultDialogs" object has the following properties:

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

Alerts

Besides using the available io.Connect alerts, you can also define an entirely custom alert app to be used by the platform. To do so, set the "url" property of the "alerts" top-level key in the system.json system configuration file of io.Connect Desktop to the location of your custom alert app:

{
    "alerts": {
        "url": "https://my-custom-alert.com"
    }
}

When an interop-enabled app invokes the request() method of the Alerts API, io.Connect Desktop will load the custom alert app instead of the default one.

Available since io.Connect Desktop 10.2

The custom alert app can use the ioAlert service object injected in the global window object to receive the alert configuration sent by the client app and to communicate back to the platform.

The ioAlert object has the following methods:

The following example demonstrates how to use the ioAlert object in a custom alert app to retrieve the alert options provided by the client app and handle user interactions:

// Retrieve the alert options provided by the client app.
const { variant, text, actions, showCloseButton } = await ioAlert.getConfig();

// Apply the alert options to the alert UI.
document.getElementById("alert-text").textContent = text;
document.getElementById("alert-container").classList.add(variant);

// Apply the current io.Connect theme.
const ioTheme = ioAlert.getTheme();

document.documentElement.classList.add(ioTheme);

// React to theme changes.
ioAlert.onThemeChanged((newTheme) => {
    document.documentElement.classList.replace(ioTheme, newTheme);
});

// Handle action button clicks.
if (actions) {
    actions.forEach((action) => {
        const button = document.createElement("button");

        button.textContent = action.title;
        button.addEventListener("click", () => {
            // Return the result to the client app and close the alert.
            ioAlert.setResult({ action: action.title });
        });
        document.getElementById("actions-container").appendChild(button);
    });
}

// Handle close button click.
if (showCloseButton) {
    document.getElementById("close-button").addEventListener("click", () => {
        ioAlert.setResult({ action: "dismissed" });
    });
}

Dialogs

⚠️ Note that the described functionalities are available when using the request() of the Dialogs API, as well as the showDialog() method of an IOConnectWindow or a Frame instance. However, it's highly recommended to use the Dialogs API to display dialogs instead of the showDialog() method.

Besides using the available io.Connect dialogs, you can also define an entirely custom dialog app to be used by the platform. To do so, set the "url" property of the "dialogs" top-level key in the system.json system configuration file of io.Connect Desktop to the location of your custom dialog app:

{
    "dialogs": {
        "url": "https://my-custom-dialog.com"
    }
}

When an interop-enabled app invokes the request() method of the Dialogs API, io.Connect Desktop will load the custom dialog app instead of the default one.

Available since io.Connect Desktop 10.2

The custom dialog app can use the ioDialog service object injected in the global window object to receive the dialog options sent by the client app and to return data back to it.

The ioDialog object has the following methods:

The following example demonstrates how to use the ioDialog object in a custom dialog app to retrieve the dialog options provided by the client app and return data back to it:

// Retrieve the dialog options provided by the client app.
const { templateName, variables } = await ioDialog.getConfig();

// Apply the dialog options to the dialog UI.
document.getElementById("dialog-title").textContent = variables.title;
document.getElementById("dialog-message").textContent = variables.text;

// Apply the current io.Connect theme.
const ioTheme = ioDialog.getTheme();

document.documentElement.classList.add(ioTheme);

// React to theme changes.
const themeHandler = newTheme => document.documentElement.classList.replace(ioTheme, newTheme);

ioDialog.onThemeChanged(themeHandler);

// React to user interaction and return the result to the client app.
// The returned data can be of any type.
const result = { buttonClicked: null, context: 42 };
// Determine the template of the requested dialog and react accordingly.
if (templateName === "MyCustomDialog") {
    result.buttonClicked = { id: "confirm", text: "Confirm" };
}

const clickHandler = () => ioDialog.setResult(result);

document.getElementById("confirm-button").addEventListener("click", clickHandler);

You can specify a custom templateName in your client app and invoke the request() method with it:

const myDialog = {
    // Specifying a custom dialog template.
    templateName: "MyCustomDialog",
    variables: {
        title: "Custom Title",
        text: "Custom Message"
    }
};
// The client app will receive the result from opening the custom dialog
// in the exact shape as returned by the custom dialog app.
const { buttonClicked, context } = await io.modals.dialogs.request(myDialog);

// Handle the dialog result with your custom logic.
handleDialogResult(responseButtonClicked, isClosed, inputs);