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