Client-Laufzeit & Personalisierung
Client-Laufzeit & Personalisierung
docmd enthält ein schlankes, headless Client-Laufzeitskript namens docmd-runtime.js, das automatisch in jedes Layout-Template eingebunden wird (inklusive des Standard-Templates und externer Themes wie summer).
Die Laufzeit stellt die Browser-API window.docmd bereit, mit der Variablen basierend auf Benutzeranmeldung, gewählten Umgebungen oder Formulareingaben in Echtzeit aktualisiert werden können — ganz ohne Neuladen der Seite.
Variablen als dynamisch deklarieren
Legen Sie in Ihrer docmd.config.json fest, welche Variablenschlüssel dynamisch sind:
{
"variables": {
"dynamic": [
"user.name",
"user.apiKey",
"selectedProject",
"activeRegion"
]
}
}
Beim Kompilieren umschließt docmd jede dynamische Variable (oder mit user. beginnende Variable) mit einem reaktiven Markierungs-Element:
pk_test_sample
Browser JavaScript-API: window.docmd
Die Client-Laufzeit bietet ein ergonomisches API:
window.docmd.var.set(key, val)
Aktualisiert Variablenwerte im gesamten DOM und in allen Codeblöcken in Echtzeit.
window.docmd.var.get(key)
Gibt den aktiven Wert einer registrierten Laufzeitvariable zurück.
window.docmd.var.list()
Liefert ein Objekt mit allen aktuell registrierten dynamischen Variablen.
window.docmd.var.sync()
Scannt neu eingefügte HTML-Fragmente und rehydriert Variablenmarker.
Code-Beispiel: Variablen aktualisieren
// Einzelne Variable setzen
window.docmd.var.set('user.apiKey', 'sk_live_99882244');
// Mehrere Variablen gleichzeitig setzen
window.docmd.var.set({
'user.name': 'Sarah Connor',
'activeRegion': 'eu-central-1'
});
Alle <span data-docmd-var="...">-Elemente und Codeblock-Token im Dokument aktualisieren sich augenblicklich.
Interaktives Codeblock-Beispiel
Ein überzeugender Anwendungsfall ist das Testen von API-Endpunkten mit benutzerdefinierten Schlüsseln:
### API-Authentifizierung
Führen Sie folgenden Befehl im Terminal aus:
```bash
curl -X GET https://api.acme.com/v1/profile \
-H "Authorization: Bearer {{ user.apiKey || 'IHR_API_SCHLUESSEL' }}"
```
Interaktive Variablen-Live-Demonstration
Nutzen Sie den folgenden Playground, um user.apiKey direkt in der Browser-Laufzeitumgebung anzupassen. Beim Ausführen oder Ändern des Codes aktualisiert docmd-runtime alle Variablen im Dokument in Echtzeit:
Der folgende Codeblock rendert dynamisch und reagiert sofort auf Variablenänderungen:
curl -X GET https://api.acme.com/v1/profile \
-H "Authorization: Bearer IHR_API_SCHLUESSEL"
Die docmd-runtime.js-Engine aktualisiert reaktive DOM-Elemente ausschließlich über .textContent. Variablenwerte werden niemals als HTML oder ausführbares Skript geparst, was DOM-basierte Injektionsangriffe selbst bei Werten aus dynamischen Benutzereingaben wirksam verhindert.
Framework-Integration
function onUserLogin(session) {
window.docmd.var.set({
'user.name': session.fullName,
'user.apiKey': session.activeToken,
'user.orgId': session.organisationId
});
}
import { useEffect } from 'react';
export function DocsPersonaliser({ user }: { user: any }) {
useEffect(() => {
if (typeof window !== 'undefined' && (window as any).docmd) {
(window as any).docmd.var.set({
'user.name': user.name,
'user.apiKey': user.apiKey
});
}
}, [user]);
return null;
}
<script setup>
import { watchEffect } from 'vue';
const props = defineProps(['currentUser']);
watchEffect(() => {
if (typeof window !== 'undefined' && window.docmd) {
window.docmd.var.set({
'user.name': props.currentUser?.name,
'user.apiKey': props.currentUser?.token
});
}
});
</script>
Auf Variablenänderungen reagieren
Über den Event-Bus können Sie Änderungen abfangen:
window.addEventListener('docmd:variable-change', (event) => {
const { key, value } = event.detail;
console.log(`Variable ${key} geändert zu:`, value);
});
Cross-Frame-Synchronisation (iFrames & Portale)
Wird die Dokumentation in einem iFrame eingebunden, kann das übergeordnete Portal Variablen via postMessage übertragen:
const docIframe = document.getElementById('docs-frame');
docIframe.contentWindow.postMessage({
type: 'docmd:set-variables',
variables: {
'user.name': 'Alex',
'user.apiKey': 'sk_live_449911'
}
}, '*');
docmd-runtime.js arbeitet völlig unabhängig von UI-Logik ausschließlich über Daten-Marker (data-docmd-var) und harmoniert perfekt mit SPA-Routern und Custom-Themes.