Dashboard-App

Dashboard-App

Wichtig

Die Dashboard-App ist in der d.velop cloud noch nicht verfügbar.

 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.
400Widget-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.
5XXEin 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).
settings.urlStringNeinURL zur 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 data
    "permissions": {
        "groups": [
            {"value": "3E093BE5-CCCE-435D-99F8-544656B98681"}
        ]
    }
}

dashboard-javascript-API

 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 aufgerufen, wenn du die Methode updateSettings der Widgeteinstellungen-API ausführst.


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)

 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>.

 Aktualisieren der Einstellungen

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


window.dashboard.WidgetSettingsAPI.updateSettings(data)