Javascript-API
- Dominik Hisler
- Sebastian Schulz
Mit der Javascript-API von brandbox können Module für spezifischen Anwendungsfälle nachgeladen, Anfragen an brandbox gestellt sowie der HTML-Inhalt einer Seite verändert werden. Nachfolgend werden die wichtigsten Bestandteile dieser API erklärt. Die Codebeispiele gehen hier immer von einer async-Funktion als aufrufender Code aus.
Mit dem nachfolgenden HTML-Code kann die Javascript-API von brandbox eingebunden werden. Die Einbindung findet in der Administrationsoberfläche sowie dem CMS automatisch statt.
<script type="module" src="{{ url }}plugin/remote/brandbox/framework/resources/js/main.js" nonce="{{httpSecurityHeaderNonce}}"></script>Beim Laden dieses Skripts werden alle notwendigen Bestandteile der API sowie über die HTML-Attribute referenzierte Module nachgeladen. Zudem wird nach Abschluss das Javascript-Event BrandboxApplicationInitialised auf dem Dokument ausgelöst.
Modulidentifikation
Ein Javascript-Modul wird der Javascript-API von brandbox in einem von drei möglichen Schemata identifiziert. Alle Schemata sind einsetzbar, wenn in den Codebeispielen der Platzhalter [Modulidentifikation] genutzt wird. Jedes Identifikationsschema erfordert einen unterschiedlichen Grundaufbau des entsprechenden Moduls. Nachfolgend werden die einzelnen Schemata erklärt.
1. Vollständige Modulidentifikation
Bei der vollständigen Modulidentifikation wird der gesamte Pfad zu dem zu ladenden Modul beginnend ab plugin/remote/ angegeben. Ein solcher Pfad ist bspw. brandbox/custom/src/Custom/Package/js/script welcher durch die Javascript-API von brandbox in die URL https://[Domain]/plugin/remote/brandbox/custom/src/Custom/Package/js/script.js?bust=[Cachezeitstempel] übersetzt und geladen wird. Ein auf diese Weise geladenes Modul muss in seinem Grundaufbau einem RequireJS-Modul entsprechen.
Grundaufbau eines RequireJS-Moduls
define([], () => {
return /* new (falls ein Singleton gewünscht ist) */ class CustomPackageScript {
constructor() {
console.log("i'm a constructor!")
}
}
})2. Globale Modulidentifikation
Eine globale Modulidentifikation wird von externen Javascript-Modulen verwendet, damit hier kein vollständiger Pfad angegeben werden muss. Globale Modulidentifikationen sind bspw. jquery oder npm/sortablejs/Sortable. Das Prefix npm kann an dieser Stelle genutzt werden, um über npm installierte Javascript-Komponenten nachzuladen. Innerhalb von brandbox sollten keine Module erstellt werden, welche über diese Identifikation referenziert werden. Module mit dieser Identifikation müssen ebenfalls der RequireJS-Moduldefinition folgen.
3. App- und Paket-Modulidentifikation
Diese Modulidentifikation wird für ES6-Moduldefinitionen genutzt und ist der RequireJS-Moduldefinition bei einer Neutentwicklung vorzuziehen. Eine App- bzw. Modulidentifikation setzt eine gültige composer.json für eine App sowie eine gültige config.json für ein Paket vorraus. Diese Modulidentifikation setzt sich aus dem Paketnamen oder dem Appnamen sowie dem relativen Pfad des nachzuladenden Moduls zusammen. Bspw. wird die App-Modulidentifikation brandbox/custom.script durch die Javascript-API in https://[Domain]/plugin/remote/brandbox/custom/resources/js/script.js?bust=[Cachezeitstempel] und die Paket-Modulidentifikation Custom/Package.script in https://[Domain]/plugin/remote/brandbox/custom/src/Custom/Package/js/script.js?bust=[Cachezeitstempel] übersetzt.
Grundaufbau eines ES6-Moduls
'use strict'
export default /* new (falls ein Singleton gewünscht ist) */ class CustomPackageScript {
constructor() {
console.log('i'm a constructor!')
}
}Module über HTML-Attribute nachladen
Es gibt in brandbox derzeit zwei Möglichkeiten ein Javascript-Modul über HTML-Attribute nachzuladen. Wird ein Modul über eines der Attribute eingebunden, muss die Methode call vorhanden sein. Die Methodensignatur unterscheidet sich durch das genutzte Attribut. Es dürfen sowohl Singletons als auch Standardinstanzen der Module genutzt werden. Beide Attribute akzeptieren eine [Modulidentifikation] als Wert.
1. data-js-Attribut
1. data-module-Attribut
Module über Javascript nachladen
Neben den HTML-Attributes können Module auch direkt im Javascript-Code nachgeladen werden. Hierfür steht die Funktion brandbox.import() zur Verfügung. Diese akzeptiert ebenfalls eine [Modulidentifikation] als Parameter. Diese Funktion ist asynchron und gibt einen Promise für das Ergebnis zurück. Innerhalb einer async-Funktion kann mithilfe von await auf das Ergebnis gewartet werden, ansonsten muss mit Promise.then() eine Ergebnisfunktion definiert werden.
Nachladen in einer asynchronen Funktion
Nachladen in einer synchronen Funktion
Eine Anfrage an brandbox senden
Für eine Anfrage an brandbox wird die FetchAPI von Javascript eingesetzt. Diese Anfrage wird hinter einer Facade der brandbox Javascript-API verwaltet, welche Hilfsfunktionen für Entwickler anbietet.