Integrating the dashboard JavaScript API

You can integrate the dashboard JavaScript API in your page as follows.

Create a script tag, add the attribute type="module" to it and use the URL "/dash/api/dashboard_api_v1.js" as the source.

<script type="module" src="/dash/api/dashboard_api_v1.js"></script>

IFrame widget JavaScript API

Available methods

You can access the IFrame widget API methods under window.dashboard.WidgetAPI.<Methode>.

Navigation

If you want to navigate to a different page, use the method navigateTo(userEvent, url). To ensure that the navigation was triggered by a user, you must specify the appropriate event (e.g. the click event).

window.dashboard.WidgetAPI.navigateTo(userEvent, url)

Outer supply

You can use the method openOuterSupply(userEvent, url) to open a resource in the outer supply. To ensure that the opening of the outer supply was triggered by a user, you must specify the appropriate event (e.g. the click event).

window.dashboard.WidgetAPI.openOuterSupply(userEvent, url)

Widget settings callback

You can use the widget settings IFrame to update the widget. To do so, you must register a callback function using the method setUpdateSettingsCallback(callback). The user can retrieve the callback function by clicking on Save.

function callback(data: unknown) {
    console.log(data)
}

window.dashboard.WidgetAPI.setUpdateSettingsCallback(callback)

Opening the settings

You can open the widget settings using the three-dot icon on the widget. However, you can also open the settings using the method openSettings(userEvent). Here too, the event triggered by the user must be specified.

window.dashboard.WidgetAPI.openSettings(userEvent)

Saving the settings

The method saveSettings(data) allows you to save the settings for a widget. These settings are saved via the dashboard app for each widget instance. You must be able to convert the settings to JSON and the JSON object must not be larger than 1 kB.

window.dashboard.WidgetAPI.saveSettings(data)

Retrieving the saved settings

You can retrieve the saved settings of a widget instance using the method getSettings(). The method returns a promise for the settings.

const data = await window.dashboard.WidgetAPI.getSettings()

Widget settings JavaScript API

The widget settings are displayed in the navigation drawer in an IFrame. The URL for this IFrame is specified during registration.

Available methods

You can access the widget settings API methods under window.dashboard.WidgetSettingsAPI.<Methode>.

Retrieving the saved settings

You can also retrieve the saved settings of a widget instance using the widget settings API, as with the IFrame widget API.

const data = await window.dashboard.WidgetAPI.getSettings()

Getter function for widget settings

In order to be able to save the settings of the IFrame widget, you must define a getter function for the settings. To do this, use the method setSettingsGetter(getter). The getter function must return the settings of the widget. You must be able to convert the settings to JSON and the JSON object must not be larger than 1 kB.

function getSettings(): unknown {
    return {
        sort: "desc"
    }
}

window.dashboard.WidgetAPI.setSettingsGetter(getSettings)

Updating the settings

warning: Deprecated: You may only use the method updateSettings if you have used the obsolete property settings.url during registration. If you have used the property content_settings.url, the method is automatically executed when you click Save.

You can notify the IFrame widget about updated settings using the method updateSettings(data).

window.dashboard.WidgetSettingsAPI.updateSettings(data)