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:

<span data-docmd-var="user.apiKey" class="docmd-var">pk_test_sample</span>

Browser JavaScript-API: window.docmd

Die Client-Laufzeit bietet ein ergonomisches API:

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' }}"

::: card "Interaktive Live-Demo" icon:play
Geben Sie unten einen benutzerdefinierten Test-API-Schlüssel ein, um den Curl-Befehl live zu aktualisieren:

<div style="margin: 12px 0;">
  <label style="display:block; font-size:12px; font-weight:600; margin-bottom:6px; opacity:0.8;">TEST-API-SCHLÜSSEL:</label>
  <input 
    type="text" 
    id="apiKeyInputDemoDe" 
    placeholder="z. B. sk_test_mein_schluessel_99" 
    oninput="window.docmd?.var?.set('user.apiKey', this.value || 'IHR_API_SCHLUESSEL')"
  />
  <script>
    (function() {
      var inp = document.getElementById('apiKeyInputDemoDe');
      if (inp && !inp.__bound) {
        inp.__bound = true;
        inp.addEventListener('input', function(e) {
          if (window.docmd && window.docmd.var) {
            window.docmd.var.set('user.apiKey', e.target.value || 'IHR_API_SCHLUESSEL');
          }
        });
      }
    })();
  </script>
</div>

```bash
curl -X GET https://api.acme.com/v1/profile \
  -H "Authorization: Bearer {{ user.apiKey || 'IHR_API_SCHLUESSEL' }}"

:::

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'
  }
}, '*');