Dieses Objekt enthält einige MorphIT-Services, die für die Entwicklung von WebWidgets hilfreich sind. 

• contextMenu
• location
• localization
• morphitLocalStorage
• overlay
• webwidgetCommunication
• webwidgetLoader
• widgetOverlay
• widgetModel

services.contextMenu

Dieser Service bietet Methoden an, mit denen das WebWidget sein Grid-Menü (ein Menü-Button wird in der rechten oberen Ecke des Widgets eingeblendet) steuern kann.

• setGridMenuItem(widgetId, item, noAdd)
• removeGridMenuItem(widgetId, item)

services.contextMenu.setGridMenuItem(widgetId, item, noAdd)

Fügt einen neuen Menü-Eintrag in das Grid-Menü des Widgets ein, oder aktualisiert einen bestehenden Eintrag mit der gleichen Item-id.

Die widgetId erhält ein WebWidget von dem von webwidgetLoader.loadWidget() zurückgegebenen Widget.

Das item ist ein Objekt mit folgender Struktur:

Item

Wird ein bestehender Menü-Eintrag aktualisiert, dann werden nur die im item-Parameter angegebenen Eigenschaften aktualisiert. So kann man zum Beispiel mit folgendem Aufruf ein bereits existierendes Menü-Item einfach deaktivieren.

morphitApi.services.contextMenu.setGridMenuItem(this.widget.id, {id:itemId, disabled:true});

Falls noAdd = true gesetzt ist, dann werden nur bestehende Menü-Einträge aktualisiert, aber keine neuen angelegt, falls kein Menü-Eintrag mit der enstprechenden Id existiert.

services.contextMenu.removeGridMenuItem(widgetId, item)

Entfernt ein vorher eingefügtes Menü-Item. Die einzige Eigenschaften, die in item definiert sein muss, ist die id.

services.location

Dieser Service bietet ein paar Methoden an, um mit der URL der MorphIT-Anwendung zu arbeiten und relative Pfade für Ressourcen aufzulösen.

• clientSearch()
• proxySearch()
• search()
• getPort()
• resolvePathStrict(relativePath, startPath?)
• getRelativePath(resource, startPath?)
• getAbsolutePath(resource, startPath?)

services.location.clientSearch() -> {name:value}

Diese Methode parst den Query-String (alles nach dem "?") der URL (aus der aktuellen Adresszeile im Browser) und liefert die übergebenen Query-Parameter als Objekt zurück.

services.location.proxySearch() -> {name:value}

Falls die MorphIT-Anwendung hinter einem Reverse-Proxy läuft, der eine URL wie "https://site.com/morphit/customer/acme" übersetzt in "https://site2.com/?customer=acme", dann liefert diese Methode nur die Query-Parameter, die von dem Reverse-Proxy hinzugefügt werden und in der Adresszeile des Browsers nicht sichtbar sind (der MorphIT-Server spielt diese Information an den Client zurück).

Die Query-Parameter werden genau wie von location.clientSearch() als Objekt zurückgegeben.

services.location.search() -> {name:value}

Diese Methode liefert alle Query-Parameter (location.clientSearch() + location.proxySearch()) als Objekt zurück, die der MorphIT-Server bei der Anfrage gesehen und an den Client zurückgespielt hat.

services.location.getPort() -> number

Diese Methode liefert die Port-Nummer aus der Adresszeile des Browsers. Falls kein Port explizit angegeben ist, wird die Portnummer aus dem verwendeten Protokoll ermittelt (http/https).

services.location.resolvePathStrict(relativePath, startPath?) -> string

Löst einen Pfad relativ zu einem Start-Pfad (default = Pfad zur index.html von MorphIT) auf und wirft einen Fehler, falls während Pfadnavigation versucht wird, per ".." aus dem Root-Pfad ("/") herauszunavigieren. 

Falls ein absoluter Pfad übergeben wird (beginnend mit "/"), dann wird der Pfad relativ zum Root-Pfad aufgelöst und der startPath-Parameter wird ignoriert.

services.location.getRelativePath(resource, startPath?) -> string

Löst den in resource übergebenen relativen Pfad relativ zum Verzeichnis von startPath (default = Pfad zur index.html von MorphIT) auf. Es findet keine Pfadauflösung im klassischen Sinne statt, die beiden Strings werden an der korrekten Stelle verbunden und falls die URL über den Browser angefragt wird, dann löst dieser die Pfadnavigation ("." und "..") auf.

services.location.getAbsolutePath(resource, startPath?) -> string

Wie location.getRelativePath(), nur dass eine absolute URL generiert wird, die auch die Server-Adresse selbst enthält.

services.localization

Dieser Service implementiert Methoden und Objekte, damit WebWidgets auf Sprach-/Locale-Änderungen reagieren können.

• onLanguageChanged(callback)
• onLocaleChanged(callback)
• registerTranslation(widgetUrl, path?)

services.localization.onLanguageChanged(callback) -> deregisterFn

Diese Methode registriert eine callback-Funktion, die bei jedem Sprachwechsel mit der neuen Sprache aufgerufen wird. Die übergebene callback-Funktion wird mit einem String-Parameter aufgerufen und die Sprache entspricht der DIN EN ISO 639-1 Alpha 2 Norm. (Bsp. "en", "de", "fr")

Die callback-Funktion wird während der Registrierung direkt mit der aktuell aktiven Sprache erstmalig aufgerufen.

Die zurückgegebene deregisterFn sollte Aufgerufen werden, um den callback zu deregistrieren, sobald dieser nicht mehr benötigt wird. Für WebWidgets sollte dies spätestens dann geschehen, wenn sie geschlossen werden (s. Widget.onDestroy()).

services.localization.onLocaleChanged(callback) -> deregisterFn

Diese Methode registriert eine callback-Funktion, die bei jeder Änderung der Locale-Information mit der neuen Locale-Information aufgerufen wird. Die Locale-Information ist ein Objekt und besteht aktuell aus folgenden Daten:

LocaleInfo

Die callback-Funktion wird während der Registrierung direkt mit der aktuell aktiven Locale-Information erstmalig aufgerufen.

Die zurückgegebene deregisterFn sollte Aufgerufen werden, um den callback zu deregistrieren, sobald dieser nicht mehr benötigt wird. Für WebWidgets sollte dies spätestens dann geschehen, wenn sie geschlossen werden (s. Widget.onDestroy()).

services.localization.registerTranslation(widgetUrl, path?) -> Translator

Mit dieser Methode kann ein WebWidget seine Übersetzungsdatei(en) anmelden und erhält ein Objekt zurück, welches die Übersetzungsdateien bei Bedarf lädt und Texte per id aus den Übersetzungsdateien liest.

Üblicherweise sollte als widgetUrl der Pfad zum WebWidget angegeben werden (s. Widget.url) und als path der relative Pfad vom Ordner des WebWidgets zur Übersetzungsdatei, bzw. zum Ordner mit den Übersetzungsdateien.

Alternativ kann als widgetUrl ein Pfad zur Übersetzungsdatei/-ordner direkt angegeben werden und path kann in dem Fall als Parameter wegfallen. In diesem Fall wird widgetUrl relativ zur index.html von MorphIT aufgelöst.

<script>
morphitApi.services.webwidgetLoader.loadWidget('widget.js').then((widget) => {
    let translator = morphitApi.service.localization.registerTranslation(widget.url, 'translations/');
    translator.translate(['hello', 'world']).then((t) => {
        console.log(t['hello'] + ' ' + t['world']);
    });
})
</script>

Falls eine .json Übersetzungsdatei angegeben wird, dann erwartet MorphIT, dass für jedes Sprachkürzel (Bsp. "de") in der JSON-Datei ein Objekt mit der Zurodnung von Id auf Text existiert. 

Falls ein Ordner als Übersetzungspfad angegeben wird, dann erwartet MorphIT, dass für jedes Sprachkürzel (Bsp. "de") eine entsprechende .json-Datei in dem Ordner (Bsp. "de.json") liegt, in welcher das Objekt mit der Zuordnung von Id auf den Text definiert ist.

Pro Übersetzungspfad wird nur ein Translator-Objekt erzeugt, sodass sich mehrere Widgets das gleicher Translator-Objekt teilen können. Die Übersetzungsdateien werden in dem Fall auch nur einmalig in den Speicher geladen.

Translator

Dieses Objekt ist zuständig für das verzögerte Laden der Übersetzungsdateien und die Übersetzung der ids in die Texte anhand der geladenen Übersetzungsdateien.

• translate(ids, variables?)

Translator.translate(ids, variables?) -> Promise<string|{id:text}>

Diese Methode lädt die Übersetzungsdatei für die aktuelle Sprache (falls noch nicht geschehen) und übersetzt anschließend die übergebenen ids (string oder Array von strings) anhand dieser Übersetzungsdatei. Eine id kann auch ein Pfad sein, falls die Übersetzungsdatei entsprechend strukturiert ist (Bsp. "dialog.title.warning"). 

Wird eine einzelne id übergeben, dann wird das Promise mit einem einzelnen string (dem übersetzten Text) erfüllt. Wird ein Array von ids übergeben, dann wird das Promise mit einem Objekt erfüllt, wobei die Schlüssel die einzelnen ids darstellen und die Werte die übersetzten Texte.

Optional kann ein beliebig strukturiertes Objekt in variables übergeben werden. In den Übersetzungsdateien können die Felder dieses übergebenen Objekts in den Übersetzungstexten per "{{pfad}}" referenziert werden. 

// Request and await translation for text literals
this.translator.translate(['dialog.info', 'language.changed'], {lang:{from:'en', to:'de'}}).then((t) => {
    // Display translated texts in a dialog
    morphitApi.services.overlay.showDialog(t['dialog.info'] + ': ' + t['language.change'], 'info');
});

Die dazugehörige Übersetzungsdatei könnte wie folgt aussehen:

{
    "dialog": {
        "info": "Information"
    },
    "language": {
        "changed": "Sprache wurde von {{lang.from}} auf {{lang.to}} geändert"
    }
}

services.morphitLocalStorage

Dieser Service bietet Zugriff auf das von MorphIT intern verwendete localStorage-Objekt. Der Service speichert Schlüssel mit einem URL-Präfix, sodass zwei MorphIT-Instanzen, die auf unterschiedlichen Pfaden auf dem gleichen Server laufen, sich nicht gegenseitig das localStorage überschreiben.

• put(key, value) - Wert setzen
• get(key) - Wert auslesen
• remove(key) - Wert entfernen
• clearAll() - Alle gespeicherten Werte entfernen
• getAll() - Liefert alle Einträge des localStorage als Objekt zurück.

services.overlay

Dieser Service bietet Zugriff auf das Lade- & Dialog-Overlay von MorphIT. Hierüber können Dialoge im Look & Feel von MorphIT geöffnet werden.

Zudem kann hierüber das Lade-Overlay (Ladekringel) für die MorphIT-Anwendung gesteuert werden. WebWidgets sollten jedoch bevorzugt services.widgetOverlay für die Anzeige eines Lade-Overlays und Statustexten verwenden, um die Nutzung der restlichen Anwendung hierdurch nicht zu beeinträchtigen.

• showDialog(message, level?, options?)
• showInputDialog(options)
• showFileDialog(text, multiSelect, webcam, fileTypePattern, onComplete)
• showThumbnailDialog(options, onComplete?)
• closeDialog()
• showWaitingElement(message?)
• closeWaitingElement()

services.overlay.showDialog(message, level?, options?)

Zeigt einen regulären Dialog (wie in DialogBox) an. Die angezeigte message kann beliebige Sonderzeichen enthalten und Zeilenumbrüche "\n" werden als solche dargestellt.

level kann einen der folgenden Werten annehmen: "info", "warning" (=default), "error", "exception", "question" und bestimmt den Text und das Styling der Titelzeile des Dialogs.

Das options-Objekt hat folgende Felder, die gesetzt werden können:

services.overlay.showInputDialog(options)

Zeigt einen Texteingabe-Dialog an, in dem 1-n Texte abgefragt werden können. Der options-Parameter ist ein Objekt mit dem folgenden Aufbau:

services.overlay.showFileDialog(text, multiSelect, webcam, fileTypePattern, onComplete)

Zeigt einen Datei-Upload-Dialog mit text als Beschreibungstext an, in welchen 1-n Dateien reingedroppt werden können. Durch anklicken des Upload-Buttons öffnet sich alternativ der native File-Explorer zur Datei-Auswahl. Der Dialog zeigt zusätzlich einen Kamera-Button an, mit welchem die Webcam geöffnet werden kann, um damit ein Foto zu schießen und dies auszuwählen.

Falls multiSelect = true ist, dann können mehrere Dateien ausgewählt werden, anderenfalls wird nur eine Datei erlaubt.

Falls webcam = true ist, dann wird die Webcam direkt für die Aufnahme eines Fotos geöffnet ohne dass vorher der entsprechende Button gedrückt werden muss.

fileTypePattern kann einen String wie "*.png" enthalten, um die Dateiauswahl im nativen File-Explorer auf den entsprechenden Dateityp einzuschränken. Falls dies nicht erwünscht ist, kann hier einfach false oder undefined übergeben werden.

onComplete(files) ist die Callback-Funktion, die aufgerufen wird, sobald der Dialog geschlossen wird. Falls der Dialog abgebrochen wurde, dann wird die Funktion mit undefined als Parameter aufgerufen, ansonsten wird ein Array von Dateien (auch falls multiSelect=false ist) aufgerufen. Dateien, die aus dem Datei-System ausgewählt wurden, werden als File-Objekte übergeben, Bilder, die mit der Webcam aufgenommen wurden, sind Objekte mit folgender Struktur:

services.overlay.showThumbnailDialog(options, onComplete?)

Blendet das Overlay mit einem angegebenen Bild ein. Das Bild wird dabei in Originalgröße dargestellt. Der Nutzer kann irgendwo auf das Overlay klicken, um es wieder zu schließen. Dieses Overlay ist für die vergrößerte Darstellung von Thumbnails gedacht.

options ist ein Objekt, welches aktuell nur das Feld imagePath definiert. Falls hier ein relativer Pfad angegeben wird, dann wird der Pfad relativ zur index.html von MorphIT interpretiert.

Der optional angegebene onComplete-Callback wird aufgerufen, sobald der Nutzer das Overlay durch klicken geschlossen hat.

services.overlay.closeDialog()

Schließt eventuell geöffnete Dialoge. Die beim Öffnen des Dialogs angemelete onConfirm/onComplete Funktion wird dabei nicht ausgelöst.

services.overlay.showWaitingElement(message?)

Hiermit wird das Overlay eingeblendet und der "Wartekringel" mit einer optionalen Status-Nachricht dargestellt.
WebWidgets sollten stattdessen WidgetOverlay.show() verwenden.

services.overlay.closeWaitingElement()

Schließt ein vorher geöffnetes Lade-/Status-Overlay.
WebWidgets sollten stattdessen WidgetOverlay.hide() verwenden.

services.webwidgetCommunication

Dieser Services kapselt die Kommunikation von WebWidgets mit ClassiX.

• registerWidget(id)

services.webwidgetCommunication.registerWidget(id) -> Channel

Mit dieser Methode meldet ein WebWidget an, dass es über einen bidirektionalen Kommunikationskanal mit dem ClassiX-Gegenstück dieses WebWidgets kommunizieren will. Die id sollte der Widget-Id des WebWidgets entsprechen, die man z.B. über webwidgetLoader.loadWidget() erhält. 

registerWidget() prüft die übergebene Widget-Id nicht auf Korrektheit. Falls eine falsche Id übergeben wird, dann können über das zurückgegebene Channel-Objekt keine Nachrichten gesendet und empfangen werden.

Hinweis: Da das JavaScript der WebWidgets erst ausgeführt werden kann, nachdem das offene WebWidget im Browser angekommen ist, sollte jede WebWidget-Kommunikation zwischen InstantView & JavaScript immer von der JavaScript-Seite aus initiiert werden. Messages, die von InstantView an ein JavaScript-WebWidget gesendet werden, bevor dieses den Kanal aktiviert hat (Channel.on()), gehen verloren.

Channel

Ein Channel repräsentiert einen bidirektionalen Kommunkationskanal zwischen ClassiX und dem konkreten WebWidget. Falls der Kanal nicht mehr benötigt wird, sollte der Kanal per close() geschlossen und abgemeldet werden.

• on(type, handler)
• send(type, data)
• close()

Channel.on(type, handler)

Registriert einen Webwidget-Handler, der jedes Mal aufgerufen wird, ClassiX and das Widget eine Webwidget-Nachricht per PushSocket mit dem übergebenen type sendet. Pro Typ kann nur ein Handler registriert werden. Wird on() ein zweites Mal mit dem gleichen Typ aufgerufen, dann gilt nur der zuletzt übergebene Handler.

Channel.send(type,data)

Sendet eine Webwidget-Nachricht an das ClassiX-WebWidget (InstantView-Seite) und implementiert die umgekehrte Funktion zu PushSocket.

Channel.close()

Schließt den Kommunikationskanal. Am Kanal angemeldete Message-Handler werden im Anschluss an close() nicht mehr aufgerufen. Diese Methode sollte immer aufgerufen werden, wenn der Kanal nicht mehr benötigt wird, oder das WebWidget geschlossen wurde.

services.webwidgetLoader

Dieser Service dient der Entwicklung von reinen JS/HTML-WebWidgets ohne Angular und bietet hierfür nur eine relevante Methode an:

• loadWidget(path)

services.webwidgetLoader.loadWidget(path?) -> Promise<Widget>

Diese Methode lädt die .js-Datei eines .html-WebWidgets. Diese .js-Datei enthält für gewöhnlich die gesamte Logik des Web-Widgets und wird im Gegensatz zum .html-Teil nur einmalig geladen.

Achtung: Diese Methode darf nur innerhalb eines Script-Blocks im .html-Teil des WebWidgets aufgerufen werden, da die Methode den Aufruf ansonsten keinem Widget zuordnen kann und den Pfad potenziell falsch auflöst.

Falls kein path Argument übergeben wurde, dann wird keine Script-Datei geladen, sondern lediglich die Widget-Struktur zurückgegeben (inklusive Promise, welches sofort resolved wird). Der Aufruf ohne path ergibt für kleine Script-WebWidgets Sinn, die per PutValue in ein WebWidget direkt eingefügt werden und keine Script-Dateien nachladen müssen, aber trotzdem Zugriff auf die Informationen aus dem Widget-Objekt benötigen.

Das von loadWidget zurückgegebene Promise enthält ein Widget-Objekt mit folgenden Eigenschaften:

Widget

Hinweis: loadWidget schreibt die oben genannten Eigenschaften auch direkt in das zurückgegebene Promise-Objekt, sodass diese Eigenschaften bereits ausgelesen werden können bevor das Promise erfüllt wird.

Codebeispiel:

<script>
(function() {
    morphitApi.services.webwidgetLoader.loadWidget('widget.js').then((widget) => {
        // now the script is loaded....
    });
})();
</script>