Home-App

Only available in german

Home App

warning: Die Home-App wird in absehbarer Zeit nicht mehr unterstützt. Verwende anstatt einer Kachel in Zukunft ein Widget.

Funktionsumfang der Home-App

Die Home-App ist die zentrale HTTP-Schnittstelle zum Bereitstellen von Features auf der Startseite der d.3ecm-Umgebung.

Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der Home-App für eigene Entwicklungen nutzen kannst.

Bereitstellen von Features

Mit dieser Funktion kannst du Features (Kacheln) bereitstellen, die mit der Home-App auf der Startseite dargestellt werden.

Folgende Anforderungen müssen erfüllt sein, damit die Features deiner App auf der Startseite angezeigt werden:

Die App muss an der HttpGateway-App registriert sein (nur On-Premises).
Die App muss eine Linkrelation (featuresdescription) zu den Features ausliefern.
Die App muss Features mithilfe des Feature-Objekts beschreiben und ausliefern.

info: Die Home-App schickt bei Anfragen an deine App die aktuelle Benutzersitzung mit. Die Home-App verwendet dafür den Header Authorization und ein Bearer-Token. Nähere Informationen dazu findest du in der API-Dokumentation zur Identityprovider-App.

Ausliefern einer Linkrelation (featuresdescription) zu den Features

Damit die Home-App die Features deiner App anzeigt, muss deine App die Features mithilfe der Linkrelation featuresdescription übermitteln. In der Antwort auf die GET-Anfrage der Home-App muss deine App die Linkrelation unter der Basisadresse mit dem Content-Type: application/hal+json ausliefern.

Repräsentation der Ressource:

{
  "_links": {
    "featuresdescription": {
      "href": string
    }
  }
}

Eigenschaft	Typ	Beschreibung	Pflicht
_links	Objekt	Linkrelationen zu den Ressourcen einer App	Ja
_links.featuresdescription	Objekt	Objekt, das den Pfad zu den angebotenen Features einer App enthält	Ja
_links.featuresdescription.href	String	Pfad, unter dem die Features der App abgerufen werden sollen	Ja

info: Beachte auch weitere Informationen zum Aufbau der _links-Eigenschaft.

Eine Antwort im JSON-Format sieht beispielsweise so aus:

{
  "_links": {
    "featuresdescription": {
      "href": "/exampleapp/features"
    }
  }
}

Beschreibung des Features-Objekts

Unter der URL href muss deine App auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausliefern.

Repräsentation der Ressource:

{
  "features": [
    {
      "id": string,
      "url": string,
      "title": string,
      "subtitle": string,
      "iconURI": string,
      "summary": string,
      "description": string,
      "color": string,
      "badge": object,
      "scriptURL": string,
    }
  ]
}

Eigenschaft	Typ	Beschreibung	Pflicht	Anmerkung
features	Liste	Das Features-Objekt enthält ein oder mehrere Feature-Objekte.	Ja
features.id	String	Eindeutige ID für diese Kachel.	Nein
features.url	String	Enthält die URL, zu der beim Klick auf diese Kachel navigiert werden soll.	Ja
features.title	String	Enthält die Überschrift der Kachel.	Ja
features.subtitle	String	Enthält die Unterüberschrift der Kachel.	Ja
features.iconURI	String	Enthält die URL zum Icon der App.	Ja	URL zu einem Icon mit der Größe 32 x 32 Pixel im PNG- oder SVG-Format.
features.summary	String	Enthält eine kurze Zusammenfassung der Funktionalität.	Ja
features.description	String	Enthält die Beschreibung, die beim Zeigen auf die Kachel mit dem Mauszeiger angezeigt wird.	Nein, optional
features.color	String	Gibt die Hintergrundfarbe der Kachel an.	Ja	Gib die Farbe in hexadezimal im Langformat #aabbcc oder Kurzformat #abc an.
features.badge.count	Integer	Angabe einer Zahl, welche zusätzlich in der Kachel als Badge dargestellt wird, z.B. Anzahl an offenen Aufgaben	Nein	Nur positive Ganzzahl erlaubt. Zahlen größer 99 werden in der Badge als "99+" dargestellt.
features.scriptURL	String	Relative URL zum JavaScript, welche im Kontext der Kachel geladen wird.	Nein	Das erste Pfadsegment muss den App-Namen enthalten, d.h. es können nur Scripte aus der eigenen App geladen werden.

info: Die Textfarbe der Kachel wird automatisch von der Home-App berechnet. Kacheln mit ähnlichen Hintergrundfarben erhalten möglicherweise unterschiedliche Textfarben.

Nachfolgend ist ein Beispiel für ein Features-Objekt, das ein Feature enthält.

{
  "features": [
    {
      "url": "/exampleapp/awesomefeature",
      "title": "Awesome Feature",
      "subtitle": "subtitle of feature tile",
      "iconURI": "/exampleapp/path/to/icon-thumbsup.png",
      "summary": "short summary of feature functionality",
      "description": "longer description of feature functionality, will be shown on tile hover",
      "color": "#ccc",
      "badge": {
        "count": 3
      },
      "scriptURL": "/exampleapp/feature-update.js"
    }
  ]
}

Aktualisieren einer Kachel per JavaScript

Du kannst eine Kachel auch per JavaScript dynamisch aktualisieren. Dazu muss deine App unterhalb der Eigenschaft scriptURL eine URL zu einer JavaScript-Ressource ausliefern.

Im Kontext des Scripts kannst du dazu die postMessage-Funktion verwenden. Gib für den Schlüssel type den Wert "feature" an und für den Schlüssel data ein Objekt mit den Kachel-Eigenschaften, welche du ändern möchtest.

postMessage({
  type: "feature",
  data: {
    title: "foo",
    subtitle: "bar",
    summary: "new summary",
    description: "new description",
    badge: { count: 2 },
  },
});

info: Das Script wird von einem Web Worker ausgeführt, welcher in einem eigenen Kontext arbeitet. Aus diesem Grund kann innerhalb des Scripts nicht auf das window-Objekt zugegriffen werden.

Die Kachel wird partiell aktualisiert, d.h. es werden nur die übergebenen Werte geändert.

Du kannst folgende Eigenschaften einer Kachel per JavaScript aktualisieren:

title
subtitle
summary
description
badge.count

Bereitstellen einer Beispielanwendung

Angenommen, du bist Entwickler einer fiktiven Feedback-App. Du möchtest für die App eine Kachel auf der Startseite bereitstellen.

Die Basisadresse ist https://example.com und die Feedback-App ist unter https://example.com/feedback/ erreichbar.

Die Home-App stellt eine GET-Anfrage an die Feedback-App auf https://example.com/feedback/:

Request

GET /feedback/ HTTP/1.1
Host: example.com
Accept: application/hal+json

Die Feedback-App antwortet darauf mit folgender Beispielantwort:

Response

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/hal+json

{
  "_links": {
    "featuresdescription": {
      "href": "/feedback/features"
    }
  }
}

Die Home-App stellt nun eine zweite Anfrage an die Feedback-App mit der URL https://example.com/feedback/features.

Request

GET /feedback/features
Host: example.com
Accept: application/hal+json

Die Feedback-App antwortet mit folgender Beispielantwort, die ein Feature enthält:

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "features": [
    {
      "url": "/exampleapp/awesomefeature",
      "title": "Awesome Feature",
      "subtitle": "subtitle of feature tile",
      "iconURI": "/exampleapp/icons/thumbsup.png",
      "summary": "short summary of feature functionality",
      "description": "longer description of feature functionality, will be shown on tile hover",
      "color": "#ccc",
      "badge": {
        "count": 3
      },
      "scriptURL": "/exampleapp/feature-update.js"
    }
  ]
}

Das Feature der Feedback-App wird nun als Kachel zusammen mit Features weiterer Apps auf dem Startbildschirm angezeigt.

info: Wegen des Cache-Verhaltens der Home-App kann es einen Moment dauern, bis die Kachel auf dem Startbildschirm angezeigt wird.