Modals
6.14.0The @interopio/modals-api library provides a way to create and manage
dialogs and alerts within the io.Connect platforms.
The Modals API is accessible via the io.modals object.
Available since io.Connect Desktop 9.9 and io.Connect Browser 4.0.
The following example demonstrates enabling the Modals API in an io.Connect Desktop app:
import IODesktop from "@interopio/desktop";
import IOModals from "@interopio/modals-api";
const initializeIOConnect = async () => {
// Initializing the Modals API.
const initOptions = {
libraries: [IOModals]
};
const io = await IODesktop(initOptions);
const alertOptions = {
variant: "success",
text: "Successfully initialized the Modals API!"
};
await io.modals.alerts.request(alertOptions);
};
initializeIOConnect().catch(console.error);
The following example demonstrates enabling the Modals API in an io.Connect Browser app:
import IOBrowser from "@interopio/browser";
import IOModals from "@interopio/modals-api";
const initializeIOConnect = async () => {
// Initializing the Modals API.
const initOptions = {
libraries: [IOModals]
};
const io = await IOBrowser(initOptions);
const alertOptions = {
variant: "success",
text: "Successfully initialized the Modals API!"
};
await io.modals.alerts.request(alertOptions);
};
initializeIOConnect().catch(console.error);
APIobject
Description
Modals API.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| alerts | AlertsAPI | Alerts API. |
||
| dialogs | DialogsAPI | Dialogs API. |
||
| version | string | Version of the Modals API. |
Methods
getStatusmethod
Signature
() => Promise<ModalsStatus>
Description
Retrieves the status of the Modals API. Use this to check whether the Modals API is available for usage (e.g., dialogs and alerts can be disabled via the platform configuration).
Actionobject
Description
Describes an alert action represented as an alert button.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| clickInterop | InteropSettings | Settings for invoking an Interop method when the alert action button is clicked. |
||
| id | string | ID for the alert action. |
||
| title | string | Title for the alert action. |
AlertRequestConfigobject
Description
Settings for displaying an alert.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| actions | Action[] | List of alert actions that will be represented as alert action buttons. |
||
| clickInterop | InteropSettings | Settings for invoking an Interop method when the alert is clicked. |
||
| data | any | Custom data to attach to the alert. |
||
| onCloseInterop | InteropSettings | Settings for invoking an Interop method when the "Close" button of the alert is clicked. |
||
| showCloseButton | boolean | true | If |
|
| target | string | "WindowContainer" | Specifies the container in which the alert will be displayed. This can be the current window container (e.g., the current Workspace), the entire io.Connect platform, or a specific window. To target a specific window, provide the Interop instance ID as a string. |
|
| text | string | Text for the alert. |
||
| ttl | number | 5000 | Interval in milliseconds after which the alert will be automatically closed. |
|
| variant | "default" | "success" | "critical" | "info" | "warning" | Alert variant to use. |
AlertsAPIobject
Description
The Alerts API provides a way to create and manage alerts within the io.Connect platform. There are predefined alert variants from which you can choose and you can configure various alert settings, such as the time to display the alerts before automatically closing them, whether to show a "Close" button, whether to target the current window or the entire platform, and more. You can also define alert actions that will be displayed as alert buttons and bind them to your custom, already registered Interop methods in order to provide functionality to your alerts.
The Alerts API is accessible via the io.modals.alerts object.
Methods
requestmethod
Signature
(config: AlertRequestConfig) => Promise<void>
Description
Sends a request to the platform for displaying an alert.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| config | AlertRequestConfig | Settings for displaying an alert. |
DialogInputobject
Description
Describes a dialog input.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| checked | boolean | Flag indicating whether the input was checked (valid only for a checkbox input). |
||
| id | string | ID of the dialog input. |
||
| type | "number" | "checkbox" | "email" | "password" | "text" | Type of the dialog input. |
||
| value | string | Value that was entered in the input (valid for all inputs other than a checkbox). |
DialogRequestConfigobject
Description
Settings for displaying a dialog.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| movable | boolean | true | If |
|
| size | { width: number; height: number; } | Size for the dialog window. |
||
| target | string | "WindowContainer" | Specifies the container in which the dialog will be displayed. This can be the current window container (e.g., the current Workspace), the entire io.Connect platform, or a specific window. To target a specific window, provide the Interop instance ID as a string. |
|
| templateName | string | Type of the dialog to show. Can be either a predefined io.Connect dialog type or a custom one.
The following predefined io.Connect dialog templates are available: |
||
| timer | { duration: number; } | Countdown timer to be displayed in the dialog, warning the user that the dialog will close automatically after the specified time. |
||
| transparent | boolean | false | If true, the io.Connect Window containing the dialog will be transparent. Available only in io.Connect Desktop. |
|
| variables | any | Variables to pass for creating the dialog. Use this to specify heading, text, action buttons, and more for the predefined io.Connect dialogs,
or to pass any other variables to your custom dialogs.
For more details on the variables expected by the different predefined io.Connect dialogs, see the |
DialogResponseobject
Description
Describes the response returned by the platform after executing a request for displaying a dialog.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| inputs | DialogInput[] | List of the available dialog inputs. |
||
| isClosed | boolean | Flag indicating whether the dialog was closed by the user (via the "Close" button, by pressing the "Escape" button, or by clicking outside the dialog window). |
||
| isEnterPressed | boolean | Flag indicating whether the user pressed the "Enter" button and the dialog was closed without selecting an action button.
In this case, the |
||
| isExpired | boolean | Flag indicating whether the dialog timer has expired and the dialog was automatically closed. |
||
| responseButtonClicked | { id: string; text: string; } | Describes the dialog button that was clicked. |
DialogsAPIobject
Description
The Dialogs API provides a way to create and manage dialogs within the io.Connect platform. There are predefined dialog templates from which you can choose and you can configure various dialog settings, such as assigning a timer for displaying the dialogs, the size of the dialog window, whether to target the current window container or the entire platform, and more.
The Dialogs API is accessible via the io.modals.dialogs object.
Methods
requestmethod
Signature
(config: DialogRequestConfig) => Promise<DialogResponse>
Description
Sends a request to the platform for displaying a dialog.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| config | DialogRequestConfig | Settings for displaying a dialog. |
InteropSettingsobject
Description
Settings for assigning an Interop method to an alert action button.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| arguments | any | Arguments for the Interop method invocation. |
||
| method | string | Name of the Interop method. |
||
| target | string | "best" | Specifies which Interop servers (app instances that have registered this Interop method) to target when invoking the Interop method.
You can target all app instances that have registered the method ( |
ModalsStatusobject
Description
Status of the Modals API.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| platformConfigured | boolean | Flag indicating whether the Modals API is available for usage (e.g., dialogs and alerts can be disabled via the platform configuration). |
ModalsContainerTypeenumeration
Description
Type of the container in which the modal will be displayed.
"Global"- the modal will target the entire io.Connect platform. Available only in io.Connect Desktop."WindowContainer"- the modal will target only container of the current window (e.g., the current Workspace).
- "Global"
- "WindowContainer"