How to...

The io.Connect Dash library offers components based on React that enable you to use io.Connect features in your apps built with the Dash framework for Python.

⚠️ Note that all io.Connect Dash components aren't represented visually and will be invisible in your apps. Their only purpose is to provide access to io.Connect functionalities.

The io.Connect Dash library is available as a package on the Python Package Index. To install it, execute the following command:

pip install dash_glue42

To reference the io.Connect Dash library in your Dash app:

import dash_glue42

When the JavaScript of the library has been loaded, a glue42dash object is injected in the global window object with the following properties:

The glue42dash object allows access to the JavaScript io.Connect instance initialized internally by the io.Connect Dash library.

⚠️ Note that your the HTML template of your app should respect the fact that libraries must be loaded before external scripts. Consider this when structuring the loading sequence of your scripts to avoid cases of failed library initialization.

To initialize the io.Connect Dash library, use the Glue42 component and pass an id for it:

import dash
import dash_glue42

app = dash.Dash(__name__)

app.layout = dash_glue42.Glue42(id="io-connect")

The Glue42 component has the following properties:

Library Configuration

The underlying io.Connect JavaScript library accepts an optional configuration object. The example below demonstrates how to enable the io.Connect Channels API by using the settings property of the Glue42 component when the app is meant to run in io.Connect Desktop:

import dash
import dash_glue42

init_settings = {
    # Enabling Channels in io.Connect Desktop.
    "desktop": {
        "config": {
            "channels": True
        }
    }
}

app = dash.Dash(__name__)

# Initializing the io.Connect library with custom settings.
app.layout = dash_glue42.Glue42(id="io-connect", settings=init_settings, children=[
    # Instantiating the Channels component.
    dash_glue42.Channels(id="io-connect-channels")
])

The following table describes the properties of the optional settings object:

⚠️ Note that in Python it isn't possible to pass a function as a value, therefore the properties of the config objects which accept a function as a value can't be set.

Configuration from JavaScript Code

You can also supply configuration settings for the initialization of the io.Connect Dash library from JavaScript code by using the libSettings property of the glue42dash object injected in the global window object. The libSettings object allows you to override the io.Connect factory functions and provide a list of io.Connect factory functions that will be initialized internally to provide access to specific functionalities.

The following example demonstrates how to enable the io.Connect Search API and override the factory function:

import IODesktop from "@interopio/desktop";
import IOSearch from "@interopio/search-api";

const settings = {
    desktop: {
        // You may need a specific version.
        factory: IODesktop,
        libraries: [IOSearch]
    }
};

window.glue42dash.libsettings = settings;

Preventing io.Connect Initialization

Since the libSettings object enables you to override the io.Connect factory functions, it's possible to entirely skip the initialization of the io.Connect library. This may be useful if your app is meant to run both within and outside of io.Connect Desktop. To prevent the initialization of the io.Connect library when running outside of io.Connect Desktop, your factory function override must return an object with a skipInit property set to true.

⚠️ Note that if the initialization of the io.Connect library has been prevented, the children of the Glue42 component won't have access to io.Connect functionalities. Consider this if you expect Input from an io.Connect Dash component or update a prop from a callback.

⚠️ Note that the skipInit property is an additional implementation only for io.Connect Dash apps. This property isn't part of the io.Connect JavaScript API.

The following example demonstrates how to determine whether the app is running in io.Connect Desktop by checking for the iodesktop object injected in the global window object only when the app is running in io.Connect Desktop. If the app is running outside of io.Connect Desktop, an override function is provided to prevent the io.Connect initialization:

// Checking for the `iodesktop` object to determine whether the app is running in io.Connect Desktop.
const inIOConnectDesktop = !!window.iodesktop;

if (inIOConnectDesktop === false) {
    const settings = {
        desktop: {
            // Preventing the io.Connect initialization if not running in io.Connect Desktop.
            factory: () => Promise.resolve({ skipInit: true })
        }
    };

    window.glue42dash.libSettings = settings;
};

To add your Dash app to the io.Connect launcher, you must create a JSON file with app definition. Place this file in the %LocalAppData%/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).

⚠️ Note that this step isn't necessary if your app is running in an io.Connect Browser project. For more details, see the App Management > App Definitions section in the io.Connect Browser documentation.

The following is an example definition of a Dash app:

{
    "title": "My Dash App",
    "type": "window",
    "name": "my-dash-app",
    "details": {
        "url": "https://example.com/my-dash-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, see the Developers > Configuration > Application section.

See also the io.Connect Dash examples on GitHub, demonstrating the various io.Connect Desktop features.

For more detailed information on the different io.Connect capabilities and APIs, see:

• Shared Contexts
• Channels
• Interop
• Window Management
• Notifications