Home-APP

Home-APP

Wichtig

Die Home-App wird in absehbarer Zeit nicht mehr unterstützt. Verwende anstatt einer Kachel in Zukunft ein Widget. Wie du ein Widget registrierst, erfährst du hier: Dashboard-API

 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.

Hinweis

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
    }
  }
}
EigenschaftTypBeschreibungPflicht
_linksObjektLinkrelationen zu den Ressourcen einer AppJa
_links.featuresdescriptionObjektObjekt, das den Pfad zu den angebotenen Features einer App enthältJa
_links.featuresdescription.hrefStringPfad, unter dem die Features der App abgerufen werden sollenJa

Hinweis

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,
    }
  ]
}
EigenschaftTypBeschreibungPflichtAnmerkung
features[]ListeDas Features-Objekt enthält ein oder mehrere Feature-Objekte.Ja
features[].idStringEindeutige ID für diese Kachel.Nein
features[].urlStringEnthält die URL, zu der beim Klick auf diese Kachel navigiert werden soll.Ja
features[].titleStringEnthält die Überschrift der Kachel.Ja
features[].subtitleStringEnthält die Unterüberschrift der Kachel.Ja
features[].iconURIStringEnthält die URL zum Icon der App.JaURL zu einem Icon mit der Größe 32 x 32 Pixel im PNG- oder SVG-Format.
features[].summaryStringEnthält eine kurze Zusammenfassung der Funktionalität.Ja
features[].descriptionStringEnthält die Beschreibung, die beim Zeigen auf die Kachel mit dem Mauszeiger angezeigt wird.Nein, optional
features[].colorStringGibt die Hintergrundfarbe der Kachel an.JaGib die Farbe in hexadezimal im Langformat #aabbcc oder Kurzformat #abc an.
features[].badge.countIntegerAngabe einer Zahl, welche zusätzlich in der Kachel als Badge dargestellt wird, z.B. Anzahl an offenen AufgabenNeinNur positive Ganzzahl erlaubt. Zahlen größer 99 werden in der Badge als "99+" dargestellt.
features[].scriptURLStringRelative URL zum JavaScript, welche im Kontext der Kachel geladen wird.NeinDas erste Pfadsegment muss den App-Namen enthalten, d.h. es können nur Scripte aus der eigenen App geladen werden.

Hinweis

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 }
  }
})

Hinweis

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.

Hinweis

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