How to...

Overview

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.

Installation

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

Referencing

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 attached to the global window object with the following properties:

Property Type Description
glueInstancePromise Promise<object> Resolves with the initialized io.Connect instance. Await this to get the io.Connect instance initialized by the library in order to use it in your own scripts or in client-side callbacks.
glueInstance object The initialized io.Connect instance. If the library hasn't finished initializing, will be undefined.
version string Version of the io.Connect Dash library.
libSettings object Configuration object that 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 for the io.Connect Dash library from JavaScript code. You can also use this to prevent the io.Connect initialization altogether.

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.

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:

Property Description
id ID of this component. Used to identify Dash components in callbacks. The ID must be unique across all components in an app.
isEnterprise Indicates whether the app is running in io.Connect Desktop. The value of this property is assigned by the framework and must not be altered by client code.
children The children of this component.
settings Optional object containing configurations for the respective io.Connect libraries.
fallback Optional component to display while initializing io.Connect.
glueReady Indicates whether the io.Connect library has initialized. The value of this property is assigned by the framework and must not be altered by client code.

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:

Property Description
type Accepts either "platform" or "client" as a value. Specifies whether this is a Main app or a Browser Client in the context of io.Connect Browser. The default is "client".
web Object with one property: config. The config property accepts a configuration object for the @interopio/browser library. You should define this object if your app is a Browser Client.
webPlatform Object with one property: config. The config property accepts a configuration object for the @interopio/browser-platform library. You should define this object if your app is a Main app in the context of io.Connect Browser.
desktop Object with one property: config. The config property accepts a configuration object for the @interopio/desktop library used in io.Connect Desktop. You should define this object if your app is an io.Connect Desktop app.

⚠️ 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 attached to 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 attached to 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;
};

App Definition

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.

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.

io.Connect Dash Concepts

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