Shell-APP

Shell-APP

 Shell Allgemein

 Wie kann ich meine Ressource in der Shell anzeigen?

Die d.api wird im Head-Element der Ressource per Script-Tag eingebunden.

<html>
  <head>
  ...
  <script src="scripts/dapi._ver_.504e3bebeb.js"></script>
  </head>
  <body></body>
</html>

Es ist auch möglich, die d.api über einen Weblink einzubinden. Entweder bindet man eine konkrete Version ein oder referenziert immer die neueste d.api-Version.

Eine konkrete Version (hier im Beispiel die Version 2.13.1) kann wie folgt eingebunden werden:

<html>
  <head>
  ...
  <script src="https://cdn.service.d-velop.cloud/dapi/v2.13.1/dapi.js"></script>
  </head>
  <body></body>
</html>

Die neueste Version wird so eingebunden:

<html>
  <head>
  ...
  <script src="https://cdn.service.d-velop.cloud/dapi/latest/dapi.js"></script>
  </head>
  <body></body>
</html>

Hinweis

Für eine konkrete Version wird ein Cache-Header von einem Jahr gesetzt, da sich diese Dateien nicht mehr ändern.

Für die neueste Version wird der Cache-Header auf 30 Sekunden gesetzt, damit Änderungen spätestens nach 30 Sekunden bezogen werden.

Beim Laden der Ressource wird während der Initialisierung der d.api kontrolliert, ob um die Ressource herum schon eine Shell geladen wurde.

Wird keine Shell gefunden, versucht die d.api unter https://_SYSTEMBASE_URI_/shell die Shell aufzurufen und übergibt den relativen Pfad der eigenen Ressource als Fragment. Daraufhin wird die Shell geladen, die dann als erste Ressource die ursprünglich aufgerufene Ressoucre mit Hilfe des URI-Fragmentes lädt. Die Ressource wird erneut geladen, wodurch auch die d.api erneut initialisiert wird.

Da nun eine Shell geladen ist oder im anderen Fall schon war, wird diese Shell in der d.api referenziert und die Funktionsaufrufe an diese weitergeleitet.

 Wie kann ich den Titel meiner Ressource ändern?

Über die d.api-Funktion dapi.publishTitle(title: string).

dapi.publishTitle('neuer Titel der Ressource');

Hinweis

Wird ein leerer String übergeben (z.B. wenn ein Wert, der anzeigt werden soll, nicht gesetzt ist), dann wird anstatt des leeren Strings folgendes [ ] angezeigt.

 Wie kann ich meine Ressource programmatisch schließen?

Über die d.api-Funktion dapi.closeResourceIfMainResource().

dapi.closeResourceIfMainResource();

Dabei ist zu beachten, dass die Funktion nur dann ausgeführt wird, wenn die aufrufende Ressource als Hauptressource angezeigt wird. Ansonsten passiert nichts.

 Wie kann ich meine Ressource programmatisch im Vollbildmodus anzeigen?

Mit der Funktion dapi.activateSingleResourceMode() kann eine Ressource im Vollbildmodus angezeigt werden.

dapi.activateSingleResourceMode();

Wichtig

Diese Funktion sollte allerdings immer mit der dapi.deactivateSingleResourceMode()-Funktion verwendet werden, um wieder in das ursprüngliche, vom Benutzer eingestellte Layout zu wechseln.

 Wie kann ich den Vollbildmodus programmatisch verlassen?

Mit der Funktion dapi.deactivateSingleResourceMode() kann wieder in das benutzerspezifische Layout gewechselt werden.

dapi.deactivateSingleResourceMode();

Wichtig

Diese Funktion sollte allerdings nur verwendet werden, wenn zuvor per dapi.activateSingleResourceMode() in den Vollbildmodus gewechselt wurde, um nicht das benutzerspezifisch eingestellte Layout zu ändern.

 Wie kann ich einen "globalen" Dialog anzeigen?

Über die Funktion dapi.openDialog(uri: string, height: number, width: number, absoluteValues?: boolean) kann ein globaler, d.h. Shell überspannender Dialog angezeigt werden. Dazu muss eine URI zu den im Dialog anzuzeigenden Inhalten angegeben werden, sowie die Höhe und die Breite des Dialogs. Wird für den optionalen Parameter absoluteValue der Wert true übergeben, dann werden die Werte für Höhe und Breite als absolute Werte interpretiert, d.h. direkt in Pixel übersetzt.

dapi.openDialog('/app/dialogresource.html', 33, 44);

Dieser Aufruf erzeugt ein Dialog-Fenster mit einer Höhe von 30 und einer Breite von 40 Prozent.

dapi.openDialog('/app/dialogresource.html', 300, 400, true);

Dieser Aufruf erzeugt ein Dialog-Fenster mit einer Höhe von 300 und einer Breite von 400 Pixel.

Wichtig

Globale Dialoge sollten nur verwendetet werden, wenn sich der Inhalt des Dialogs auf die gesamte Shell und deren Inhalte bezieht. Für Inhalte, die sich auf die Ressource beziehen, bitte ressourcen-interne Dialoge verwenden, damit der Anwender weiß, von wem der Dialog erzeugt wurde.

Hinweis

Die übergebenen Höhen- und Breitenwerte werden beim Erzeugen des Dialogs in entsprechende CSS-Klassen übersetzt. Dadurch können die tatsächlich verwendeten Werte im Browser von den in der Funktion übergebenen Werten abweichen. Außer der absoluteValue ist true, dann werden die Werte direkt als Pixelwerte gesetzt.

Um den Dialog zu schließen, kann der Benutzer einfach neben den Dialog auf den Backdrop (der abgedunkelte Bereich im Hintergrund) klicken.

Um den Dialog zu schließen, nach dem der Benutzer im Dialog eine Aktion ausgeführt hat, muss programmatisch dapi.closeDialog() aufgerufen werden. Wird diese Funktion ausgerufen, ohne das ein Dialog angezeigt wird, geschieht nichts.

 Navigation in der Shell

Die Shell bietet die Möglichkeit, von einer Ressource zu einer anderen Ressource zu navigieren. Prinzipiell geschieht das immer dann, wenn von einem Kontext in einen anderen Kontext gewechselt werden soll, z.B. wenn durch die Suche in einem Repository eine Trefferliste bereitgestellt wird und man dann mit einem bestimmten Dokument arbeiten will. Dann wechselt man aus dem Suche-Kontext in den Dokument-Kontext.

 Wie kann ich zu einer anderen Ressource navigieren?

Die Navigation zu einer anderen Ressource kann über ein einfachen Anchor-Tag ausgelöst werden, das im Target-Attribute den Wert dapi_navigate setzt.

<a href="/pfad/zur/neuen/ressource" target="dapi_navigate">andere Ressource</a>

Das funktioniert auch für Anchor-Tags mit enthaltenden Kindelementen.

<a href="/pfad/zur/neuen/ressource" target="dapi_navigate">
  <div>
      <p>
          Klick mich!
      </p>
  </div>
</a>

Natürlich ist es auch möglich, mit der Funktion die dapi.navigate(uri: string) aus JavaScript heraus eine Navigation auszulösen.

dapi.navigate('/pfad/zu/Ressource[.html]');

 ContextActions

In der Shell gibt es das Konzept der Kontext-Aktionen. Das sind Aktionen, die alle in Bezug auf der angezeigten Ressource ausgelöst werden können. Dabei wird zwischen navigierenden und nicht navigierenden Aktionen unterschieden. Eine navigierende Aktionen könnte z.B. sein, wenn man von einem Dokument zu der beinhaltenden Akte navigieren möchte.

Außerdem gibt es nicht navigierende ContextActions. Diese lösen Aktionen aus, die auch im Kontext der angezeigten Ressource stattfindet, sich aber eben auf die Ressource selbst auswirken. Zum Beispiel wenn eine Aufgabe als erledigt markiert oder weitergeleitet werden soll.

 Wie kann ich ContextActions anzeigen?

ContextActions können über das Link-Tag im Head der HTML-Seite registriert werden.

<html>
  <head>
  ...
  <link rel="ctxaction" type="text/html" href="/shell/docs/details.html" title="Name der ContextAction" data-icon="/relativer/pfad/zu/ctxAct.png" />
  </head>
  <body></body>  
</html>

ContextActions können auch aus JavaScript heraus registriert werden. Dazu bietet die d.api die Funktion dapi.setContextActions(contextActions: IContextAction[]). Dieser kann ein Array von ContextActions übergeben werden, die dann dem Benutzer angezeigt werden.

dapi.setContextActions( [
  {
      type: "text/html",
      href: "relativer/pfad/zu/Ressource[.html]",
      title: "ContextActionName",
      icon: "relativer/pfad/zu/ContextActionIcon.png"
  }
] );

 Wie kann ich ContextActions ausblenden?

Um ContextActions auszublenden, ruft man dapi.setContextActions() mit einem leeren Array auf.

dapi.setContextActions([])

 Event-Handling

 Wie kann ich Änderungen an meinen Ressourcen mitteilen?

Hat sich der Status einer Ressource geändert oder wurde eine Ressource gelöscht, so besteht u.U. die Notwendigkeit, andere Ressourcen, die eine inhaltliche Abhängigkeit haben, darüber zu informieren. Zum Beispiel, damit diese sich selber aktualisieren können.

Mit der Funktion dapi.dispatchResourceEvent(event: IResourceEvent) kann ein entsprechendes Event gefeuert werden, auf welches andere Ressourcen, die sich auf diese Events registriert haben, reagieren können. Dazu muss man ein ResourceEvent erzeugen, welches den Event-Typ (changed oder deleted) und die URI der Ressource als Parameter erwartet und das dann über die dispatchResourceEvent-Funktion an die registrierten Event-Listener propagiert wird. Die URI der Ressource ist notwendig, damit registrierte Event-Listener entscheiden können, ob das Event relevant ist oder ignoriert werden kann.

 Wie kann ich auf Events anderer Ressourcen reagieren?

Indem man sich mit der Funktion dapi.addResourceEventListener(eventType: string, callback: (event: IResourceEvent) => void) auf ResourceEvents registriert. Wird ein entsprechendes Event gefeuert, auf das man sich registriert hat, dann wird der Callback aufgerufen. Darin kann dann auf die Änderungen an der Ressource oder das Löschen reagiert werden.

Hinweis

Bei der Umsetzung wurde sich an der Implementierung der Event-Verarbeitung im Browser orientiert (vgl. Creating and triggering events).

 Wie kann ich mich benachrichtigen lassen, dass meine Ressource angezeigt wird?

Über die dapi-Funktion dapi.setResourceVisibilityChangedCallback(callback: (isResourceVisible: boolean) => void) kann der Shell eine Funktion (ein sogenannter Callback) übergeben werden, die immer dann aufgerufen wird, wenn sich die Sichtbarkeit der Ressource ändert, also wenn sie entweder ein- oder ausgeblendet wird.

dapi.setResourceVisibilityChangedCallback(function(isResourceVisible) {
        if (isResourceVisible) {
            console.log(`Die Ressource ist sichtbar.`);
        } else {
            console.log(`Die Ressource ist nicht sichtbar.`);
        }
    });

An den Callback wird beim Aufruf als Parameter ein boolscher Wert übergeben, der den Wert true hat, wenn die Ressource sichtbar ist und false, wenn diese nicht angezeigt wird. Damit kann man beispielsweise ein automatisches Aktualisieren der Ressource aussetzen, solange die Ressource ausgeblendet ist.