Dashboard-App

Dashboard-App

 Einleitung

 Änderungshistorie

DatumÄnderungen
2023-08-01- Die Eigenschaft settings.url und die Methode updateSettings werden nicht mehr unterstützt.
- Die Eigenschaft content_settings.url und die Methode setSettingsGetter wurden hinzugefügt.

 Limitieren von Aufrufzahlen

Für alle Schnittstellen gelten Begrenzungen hinsichtlich der Aufrufzahlen innerhalb von bestimmten Zeitbereichen. Beim Überschreiten dieser Begrenzungen wird der HTTP-Status-Code 429 (too many requests) zurückgegeben.

 Registrieren eines Widgets

Die Registrierung eines Widgets muss mit einer App-Session erfolgen. Wie du eine App-Session ausstellen kannst, ist im Abschnitt Inter-App-Kommunikation mit App-Sessions der Identityprovider-App beschrieben.

Wichtig

Die Authentifizierung muss mit einem Bearer-Token im Authorization-Header erfolgen. Eine Authentifizierung via Cookie ist nicht möglich.

Eine App kann Widgets nur im eigenen Namensraum der App registrieren.

Du kannst ein neues Widget für deine App wie folgt mit der Dashboard-App bekannt machen.


Verwende eine HTTP-PATCH-Anforderung an den Pfad /dash/api/widget-registrations/<app-namespace>/<id>. Aufbau: [a-z-]/[a-z][a-z0-9]. Der <id> Teil nach dem / darf max zwölf Zeichen lang sein. Zum Beispiel acme-example/foobar.

Request

PATCH /dash/api/widget-registrations/<appname>/<widgetID>
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <AuthSessionId of an app session>

{
    "widget": {
        "type": "shortcut",
        "title": {
            "en": "My tasks",
            "de": "Meine Aufgaben"
        },
        "subtitle": {
            "en": "My open tasks",
            "de": "Meine offenen Aufgaben"
        },
        "icon": {
            "url": "https://example.com/tasks.svg"
        },
        "target": {
            "url": "/tasks/tasks?filter=foo"
        },
        "query": {
            "badge": {
              "url": "/tasks/tasks?type=badge"
            }
        }
    }
}

Folgende HTTP-Statuscodes können von der Dashboard-App zurückgegeben werden:

StatuscodeNameBedeutung
200OKRegistrierung oder Update des Widgets wurde erfolgreich durchgeführt.
400
Widget-Registrations-Objekt ist nicht gültig
401Not AuthorizedAuthentifizierung via App-Session ist notwendig
403ForbiddenRegistierung eines Widget ist nur innerhalb des eigenen Widgetnamensraums möglich. Bitte stelle sicher, dass der erste Teil der Widgetregistrierungs-ID dem Appnamen entspricht.
429Too Many RequestsRate-Limit wurde erreicht.
5XX
Ein unerwarteter Fehler ist aufgetreten.

 Eigenschaften des Widget-Registrations-Objekt

EigenschaftTypPflichtBeschreibung
widgetObjektJaSiehe Widget-Arten für den Aufbau
permissionsObjektNeinSiehe Berechtigungen für den Aufbau

 Unterstützte Widgetarten

 Shortcut

Nutze dieses Widget, um dem Anwender einen Absprung in deine App zu ermöglichen.

 Eigenschaften des Shortcut-Widget-Objekts
EigenschaftTypPflichtBeschreibung
typeStringJaWert für Absprungwidget "shortcut"
titleObjektJasiehe Sprachenobjekt
subtitleObjektNeinsiehe Sprachenobjekt
icon.urlStringJaURL zu einem Icon (SVG oder PNG)
target.urlStringJaURL zur Zieladresse (Wenn die Zieladresse im alten Navigationsverhalten von d.ecs shell angezeigt werden soll, gib den Query-Parameter oldBehavior=true mit an.)
query.badge.urlStringNeinSiehe Query-Badge
 Aufbau des Query-Badge-Objekts

Folgendes Objekt muss unter der im Shortcut-Widget angegebenen query.badge.url ausgeliefert werden.

EigenschaftTypPflichtBeschreibung
badge.countIntegerJaIst der Wert größer 0, wird ein Badge am Widget angezeigt. Werte größer 99 werden mit 99+ dargestellt.

 List

Nutze dieses Widget, um ein Listenwidget anzuzeigen.

 Eigenschaften des List-Widget-Objekts
EigenschaftTypPflichtBeschreibung
typeStringJaWert für Listenwidget "list"
titleObjektJasiehe Sprachenobjekt
subtitleObjektNeinsiehe Sprachenobjekt
icon.urlStringJaURL zu einem Icon (SVG oder PNG)
target.urlStringJaURL zur Zieladresse (Wenn die Zieladresse in der alten Shell angezeigt werden soll, gib den Query-Parameter oldBehavior=true mit an.)
query.content.urlStringJaSiehe Listeninhalt
query.content.navigationStringNeinNavigation nimmt die Werte dapiNavigate, innerSupply oder outerSupply an. Bei einem unbekannten oder nicht festgelegtem Wert wird outerSupply als Fallback verwendet.
footer.urlStringNeinURL, die im Outer-Supply der Shell geöffnet wird.
footer.labelObjektNeinsiehe Sprachenobjekt

 IFrame

Nutze dieses Widget, um externe Inhalte per IFrame anzuzeigen.

 Eigenschaften des Iframe-Widget-Objekts
EigenschaftTypPflichtBeschreibung
typeStringJaWert für Iframewidget "iframe"
titleObjektJasiehe Sprachenobjekt
subtitleObjektNeinsiehe Sprachenobjekt
icon.urlStringJaURL zu einem Icon (SVG oder PNG)
target.urlStringJaURL zur Zieladresse (Wenn die Zieladresse in der alten Shell angezeigt werden soll, gib den Query-Parameter oldBehavior=true mit an.)
size.min_wIntegerNeinMinimale Breite des Widgets. Erlaubte Werte 2 ≤ x ≤ 18
size.min_hIntegerNeinMinimale Höhe des Widgets. Erlaubte Werte 2 ≤ x ≤ 16
source.urlStringJaURL zur HTML-Ressource, die im IFrame eingebunden werden soll. Die URL muss eine absolute Pfadreferenz sein, d.h. mit einem führenden Slash / anfangen (bspw. /foobar/ressource.html und nicht foobar/ressource.html).
content_settings.urlStringNeinURL zu einer Einstellungsseite für den IFrame-Inhalt des Widgets. Die Einstellungen werden pro Widget-Instanz gespeichert. Die URL muss eine absolute Pfadreferenz sein, d.h. mit einem führenden Slash / anfangen (bspw. /foobar/ressource.html und nicht foobar/ressource.html).
Für weitere Informationen zu Widgeteinstellungen, siehe Widgeteinstellungen Javascript-API.
settings.urlStringNeinDEPRECATED: Diese Eigenschaft ist obsolet. Bitte verwende stattdessen die Eigenschaft content_settings.url.
URL zu einer Einstellungsseite für das Widget. Die URL muss eine absolute Pfadreferenz sein, d.h. mit einem führenden Slash / anfangen (bspw. /foobar/ressource.html und nicht foobar/ressource.html).

 Eigenschaften des Sprachenobjekts

EigenschaftTypPflichtBeschreibung
Sprach-TagStringGib mindestens eine Sprache an.

 Listeninhalt

Deine App muss unter der bei query.content.url angegeben URL folgendes JSON-Objekt zurückliefern.

EigenschaftTypPflichtBeschreibung
entriesArrayJaEnthält alle Listeneinträge. Für jeden Eintrag wird ein Eintragobjekt angegeben.
line_variantStringNeinLegt die Anzahl der Zeilen pro Element fest. Wenn kein Wert festgelegt ist, wird eine Zeile angezeigt. Gib für zwei Zeilen den Wert twoline an.
leading_element_typeStringNeinLegt den Typ des vorranstehenden Elementes fest. Du kannst auswählen zwischen icon oder image. Wenn kein Wert angegeben wird, wird kein Element angezeigt.
trailing_element_typeStringNeinLegt den Typ des nachstehenden Elementes fest. Du kannst auswählen zwischen icon oder caption. Wenn kein Wert angegeben wird, wird kein Element angezeigt.

 Eintragobjekt

EigenschaftTypPflichtBeschreibung
title.textStringJaEnthält die Überschrift des Eintrags.
title.colorStringNeinLegt die Farbe der Überschrift fest. Gib den Farbwert bitte hexadezimal an, bspw. #112233.
subtitle.textStringNeinEnthält den Untertitel des Eintrags.
subtitle.colorStringNeinLegt die Farbe des Untertitels fest. Gib den Farbwert bitte hexadezimal an, bspw. #112233.




fontModeStringNeinLegt den Stil des Textes fest. Du kannst auswählen zwischen bold oder crossed-out.
lead_element.material_iconStringNeinLegt das vorranstehende Icon fest. Der Wert muss ein gültiges Material Icon sein. Für die Verwendung eines Material-Icons, lege leading_element_type auf icon fest.
lead_element.icon_colorStringNeinLegt die Farbe des vorranstehenden Icons fest. Gib den Farbwert bitte hexadezimal an, bspw. #112233.




lead_element.image_urlStringNeinURL zu einem Bild (SVG oder PNG). Für die Verwendung eines Bildes, leg leading_element_type auf image fest.
lead_element.image_sizeStringNeinLegt die Größe des Bildes fest.Du kannst auswählen zwischen icon, avatar, medium oder large.
trail_element.material_iconStringNeinLegt das nachstehende Icon fest. Der Wert muss ein gültiges Material Icon sein. Für die Verwendung eines Bildes, leg trailing_element_type auf icon fest.
trail_element.icon_colorStringNeinLegt die Farbe des nachstehenden Icons fest. Gib den Farbwert bitte hexadezimal an, bspw. #112233.




trail_element.captionStringNeinEnthält den Text, der am Ende des Eintrags angezeigt werden soll. Für die Verwendung eines Bildes, leg trailing_element_type auf caption fest.
trail_element.caption_colorStringNeinLegt die Farbe der Caption fest. Gib den Farbwert bitte hexadezimal an, bspw. #112233.




target.urlStringNeinURL, zu der beim Klick auf den Eintrag weitergeleitet wird.

 Berechtigungen

Optional kannst du Berechtigungen für das Widget mitgeben. Ohne Angabe von Berechtigungen sind Widgets für alle authentifizierten Anwender sichtbar, ausgeschloßen sind externe Anwender.

Ob ein Anwender das Widget sehen darf, wird durch eine ODER-Verknüpfung geprüft, d.h. zur Laufzeit wird geprüft, ob der Anwender in "Gruppe A" ODER "Gruppe B" ODER "Gruppe C" ist.

 Aufbau

EigenschaftTypPflichtBeschreibung
groupsArrayListe von Gruppenobjekten

Gruppenobjekt

EigenschaftTypPflichtBeschreibung
valueStringJaUUID (case insensitiv)

Beispiel

{
    "widget": {
        //... Widget data
    },
    "permissions": {
        "groups": [
            {
                "value": "3E093BE5-CCCE-435D-99F8-544656B98681"
            }
        ]
    }
}


Dashboard Javascript-API

 Einbinden der Dashboard Javascript-API

Du kannst die Dashboard Javascript-API wie folgt in deine Seite einbinden.

Erstelle ein Script Tag, füge das Attribut type="module" hinzu und verwende als Quelle die Url "/dash/api/dashboard_api_v1.js".


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

 IFrame-Widget Javascript-API

 Verfügbare Methoden

Die Methoden der IFrame-Widget API erreichst du unter window.dashboard.WidgetAPI.<Methode>.

 Navigieren

Wenn du zu einer anderen Seite navigieren möchtest, verwende die Methode navigateTo(userEvent, url). Um sicherzustellen, dass die Navigation von einem Anwender ausgelöst wurde, musst du das entsprechende Event (z.B. das Klickevent) angeben.


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

 Outer Supply

Mit der Methode openOuterSupply(userEvent, url) kannst du eine Ressource im Outer Supply öffnen. Um sicherzustellen, dass das Öffnen des Outer Supplies von einem Anwender ausgelöst wurde, musst du das entsprechende Event (z.B. das Klick-Event) angeben.


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

 Widget-Einstellungen Callback

Über den Widgeteinstellungen-IFrame kann das Widget aktualisiert werden. Hierfür musst du eine Callback-Funktion mithilfe der Methode setUpdateSettingsCallback(callback) registrieren. Die Callback-Funktion wird beim Klick des Anwendenden auf Speichern aufgerufen.


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

window.dashboard.WidgetAPI.setUpdateSettingsCallback(callback)

 Öffnen der Einstellungen

Die Widgeteinstellungen kannst du über das Dreipunktesymbol am Widget öffnen. Zusätzlich kannst du die Einstellungen aber auch mit der Methode openSettings(userEvent) öffnen. Auch hier muss das Event, das durch den Anwender ausgelöst wurde, angeben.


window.dashboard.WidgetAPI.openSettings(userEvent)

 Speichern der Einstellungen

Mithilfe der Methode saveSettings(data) kannst du Einstellungen für ein Widget speichern. Diese Einstellungen werden durch die Dashboard-App pro Widgetinstanz gespeichert. Die Einstellungen müssen nach JSON konvertierbar sein und das JSON-Objekt darf nicht größer als 1kB sein.


window.dashboard.WidgetAPI.saveSettings(data)

 Abrufen der gespeicherten Einstellungen

Die gespeicherten Einstellungen einer Widgetinstanz kannst du mit der Methode getSettings() abrufen. Die Methode gibt ein Promise für die Einstellungen zurück.


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

 Widgeteinstellungen Javascript-API

Die Widgeteinstellungen werden im Navigation Drawer in einem IFrame angezeigt. Die URL für diesen IFrame wird bei der Registrierung angegeben.

 Verfügbare Methoden

Die Methoden der Widgeteinstellungen-API erreicht du unter window.dashboard.WidgetSettingsAPI.<Methode>.

 Abrufen der gespeicherten Einstellungen

Die gespeicherten Einstellungen einer Widgetinstanz kannst du wie bei der IFrame-Widget API ebenfalls mithilfe der Widgeteinstellungen-API abrufen.


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

 Getter-Funktion für Widget-Einstellungen

Damit die Einstellungen des IFrame-Widgets gespeichert werden können, musst du eine Getter-Funktion für die Einstellungen festlegen. Verwende hierfür die Methode setSettingsGetter(getter). Die Getter-Funktion muss die Einstellungen des Widgets zurückgeben. Die Einstellungen müssen nach JSON konvertierbar sein und das JSON-Objekt darf nicht größer als 1kB sein.


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

window.dashboard.WidgetAPI.setSettingsGetter(getSettings)

 Aktualisieren der Einstellungen

Wichtig

Deprecated: Du kannst die Methode updateSettings nur verwenden, wenn du die obsolete Eigenschaft settings.url bei der Registrierung verwendet hast. Wenn du die Eigenschaft content_settings.url verwendet hast, wird die Methode automatisch beim Klick auf Speichern ausgeführt.

Die aktualisierten Einstellungen kannst du dem IFrame-Widget mit der Methode updateSettings(data) mitteilen.


window.dashboard.WidgetSettingsAPI.updateSettings(data)

Widget Converter

Home-App Feature zu Dashboard-App Widget Konverter
Home-App Feature → Dashboard-App Widget

Dieses Tool konvertiert Home-App Features zu Dashboard-App Widgets.

  1. Füge ein Home-App Feature JSON für eine bestimmte Sprache ein und wähle die jeweilige Sprache aus
  2. Füge den technischen App Name im App Name Feld ein
  3. Klicke auf "Konvertieren"
  4. Füge das JSON für eine andere Sprache ein, wähle die jeweilige Sprache aus und klicke auf "Sprache hinzufügen"
  5. Wiederhole Schritt vier, bis alle Sprachen hinzugefügt sind
  6. Du kannst nun die fertigen Dashboard-App Widget JSONs kopieren und registieren