Javascript-API

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.

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.

'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

data-js="[Modulidentifikation]"

/**
 * @param {*} node jQuery-Instanz des HTML-Elements mit dem data-js-Attribut
 * @param {Element} element Element-Instanz des HTML-Elements mit dem data-js-Attribut
 * 
 * @returns {?Promise<void>} Es darf optional ein Promise zurückgegeben werden
 */
/* async */ call (node, element) {}

1. data-module-Attribut

data-module="[Modulidentifikation]"

/**
 * @param {Element} element Element-Instanz des HTML-Elements mit dem data-js-Attribut
 * 
 * @returns {?Promise<void>} Es darf optional ein Promise zurückgegeben werden
 */
/* async */ call (element) {}

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.

const custom = await brandbox.import('[Modulidentifikation]')

brandbox.import('[Modulidentifikation]').then(/* async */ (custom) => {
	// Innerhalb von custom steht nun das Modul zur Verfügung
})

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.

const response = await brandbox.import({request: 'Custom/Package.request'}) // Weitere Parameter stehen über die Codevervollständigung zur Verfügung

const request = (await brandbox.network()).build()

// 'request'-Parameter für brandbox setzen
request.request = 'Custom/Package.request'

// Anfragetyp aus 'GET' festlegen
request.method = request.constructor.METHOD_GET

// Parameter hinzufügen
request.parameter.append('something', 'strange')

// Kopfzeile festlegen
request.header.append('x-custom-header', 'content')

// Weitere Parameter stehen über die Codevervollständigung zur Verfügung
// CSRF-Parameter werden nicht automatisch ergänzt
// StackResponses werden nicht automatisch verarbeitet

const response = await request.process()
const content = await response.response.text()

console.log(response.status)
console.log(content)

StackResponse-Listener ergänzen

const network = await brandbox.network()

network.stack.attach('CustomStackResponseType', async (response) => {
	console.log(response)
})