# Dash

Source: https://docs.interop.io/desktop/getting-started/how-to/interop-enable-your-apps/dash/index.html

## Overview

The [io.Connect Dash](https://pypi.org/project/dash-glue42/) library offers components based on React that enable you to use io.Connect features in your apps built with the [Dash](https://dash.plotly.com/) 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](https://pypi.org/project/dash-glue42/) library is available as a package on the Python Package Index. To install it, execute the following command:

```cmd
pip install dash_glue42
```

## Referencing

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

```python
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:

| Property | Type | Description |
|----------|------|-------------|
| `glueInstance` | `object` | The initialized io.Connect instance. If the library hasn't finished initializing, will be `undefined`. |
| `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. |
| `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](#initialization-preventing_ioconnect_initialization) altogether. |
| `version` | `string` | Version of the io.Connect Dash library. |

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:

```python
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 |
|----------|-------------|
| `children` | The children of this component. |
| `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. |
| `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. |
| `settings` | Optional object containing configurations for the respective io.Connect libraries. |

### Library Configuration

The underlying io.Connect JavaScript library accepts an optional configuration object. The following example demonstrates how to enable the io.Connect [Channels API](https://docs.interop.io/desktop/capabilities/data-sharing/channels/dash/index.md) by using the `settings` property of the `Glue42` component when the app is meant to run in **io.Connect Desktop**:

```python
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 optional settings object has the following properties:

| Property | Description |
|----------|-------------|
| `desktop` | Object with one property: `config`. The `config` property accepts a [`Config`](https://docs.interop.io/desktop/reference/javascript/io.connect%20desktop/config/index.md) for the [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) library used in **io.Connect Desktop**. You should define this object if your app is an **io.Connect Desktop** app. |
| `type` | Accepts either `"platform"` or `"client"` as a value. Specifies whether this is a [Main app](https://docs.interop.io/browser/developers/browser-platform/overview/index.md) or a [Browser Client](https://docs.interop.io/browser/developers/browser-client/overview/index.md) in the context of **io.Connect Browser**. The default is `"client"`. |
| `web` | Object with one property: `config`. The `config` property accepts a [configuration object](https://docs.interop.io/browser/reference/javascript/io.connect%20browser/config/index.md) for the [`@interopio/browser`](https://www.npmjs.com/package/@interopio/browser) library. You should define this object if your app is a [Browser Client](https://docs.interop.io/browser/developers/browser-client/overview/index.md). |
| `webPlatform` | Object with one property: `config`. The `config` property accepts a [configuration object](https://docs.interop.io/browser/developers/browser-platform/setup/index.md#configuration) for the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library. You should define this object if your app is a [Main app](https://docs.interop.io/browser/developers/browser-platform/overview/index.md) in the context of **io.Connect Browser**. |

> ⚠️ *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:

```javascript
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:

```javascript
// 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](https://docs.interop.io/desktop/capabilities/launcher/index.md), you must create a JSON [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file for it. Place this file in the `<installation_location>/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](https://docs.interop.io/browser/capabilities/app-management/index.md#app_definitions) section in the **io.Connect Browser** documentation.*

The following is an example definition of a Dash app:

```json
{
    "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 on defining apps, see the [Developers > Configuration > Application](https://docs.interop.io/desktop/developers/configuration/application/index.md) section.*

> ℹ️ *See also the [io.Connect Dash examples](https://github.com/InteropIO/dash-example) 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:

- [Shared Contexts](https://docs.interop.io/desktop/capabilities/data-sharing/shared-contexts/dash/index.md)
- [Channels](https://docs.interop.io/desktop/capabilities/data-sharing/channels/dash/index.md)
- [Interop](https://docs.interop.io/desktop/capabilities/data-sharing/interop/dash/index.md)
- [Window Management](https://docs.interop.io/desktop/capabilities/windows/window-management/dash/index.md)
- [Notifications](https://docs.interop.io/desktop/capabilities/notifications/dash/index.md)