Dynamische PlantUML-Diagramme mit Bedingungen

Dynamische Sequenzdiagramme in PlantUML: Variablen und Bedingungen

PlantUML unterstützt Preprocessing mit Variablen und Bedingungen, wodurch dynamische Sequenzdiagramme möglich werden. Benutzer können Detailstufen mit Schaltern steuern und verschachtelte Logik ein- oder ausblenden, ohne separate Artefakte zu erstellen.

Stellen Sie sich vor, Sie dokumentieren einen API-Endpunkt zum Erstellen von Bestellungen, der Dutzende interner Prüfungen auslöst. Ein vollständiges Diagramm wird unübersichtlich, und das Wechseln zwischen mehreren statischen Versionen ist ineffizient.

Diagrammentwurf vorbereiten

Der Basisdiagrammtext wird mit Variablen und Bedingungen erweitert. Hier ein Beispiel:

participant Bob as b
participant Alice as a

!$aliceThoughts = "No"
!$bobThoughts = "No"

b -> a: Hi!

!if ($aliceThoughts == "Yes")
activate a
a->a: Oh my god, he messaged me!
a->a: What to do, what to say..
create participant Lisa as l
a -> l: Bob messaged me, what should I do?
activate l
l -> a: Just reply to him, gosh
deactivate l
!endif

a->b: Hi!
deactivate a

!if ($bobThoughts == "Yes")
activate b
b->b: She replied o_O
!endif

b->a: Uh... How are you?
deactivate b

Die Variablen $aliceThoughts und $bobThoughts steuern die Sichtbarkeit von Codeblöcken. Der PlantUML-Preprozessor bewertet Bedingungen während des Renderns.

HTML-Oberfläche für Steuerelemente

Schalter werden mit HTML-Formularen und JavaScript erstellt. Benutzer wählen Detailstufen aus, der Code aktualisiert den Diagrammtext dynamisch und erzeugt das Bild.

<form>
  <label for="aliceThoughts">Alice' Gedanken anzeigen:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">Nein</option>
    <option value="yes">Ja</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Bobs Gedanken anzeigen:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">Nein</option>
    <option value="yes">Ja</option>
  </select>
</form>

JavaScript lauscht auf Änderungen in den Select-Elementen, injiziert Werte in die PlantUML-Vorlage und ruft den Encoder auf, um eine URL zu generieren.

Text für PlantUML-API kodieren

PlantUML bietet eine HTTP-API zum Rendern: https://www.plantuml.com/plantuml/png/<encoded_text>. Sie unterstützt PNG- und SVG-Formate.

Einfache Methode (Hex)

Konvertiert UTF-8-Text zu Hex mit ~h-Präfix:

function toHex(uml) {
  const umlFormatted = `@startuml\r\n${uml}\r\n@enduml`;
  const utf8 = unescape(encodeURIComponent(umlFormatted));
  var result = '';
  for (var i=0; i<utf8.length; i++) {
    result += utf8.charCodeAt(i).toString(16).padStart(2, '0');
  }
  return `https://www.plantuml.com/plantuml/png/~h${result}`;
}

Ideal für kurze Diagramme. Einschränkung: URL-Länge (ca. 8 KB).

Erweiterte Methode (Deflate + Custom Base64)

• Deflate-Kompression.
• Kodierung im PlantUML-Base64: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Bewältigt große Diagramme durch Kompression.

function encodePlantUml(data) {
    const base64Map = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_';
    let result = '';
    for (let i = 0; i < data.length; i += 3) {
        const b1 = data[i];
        const b2 = i + 1 < data.length ? data[i + 1] : 0;
        const b3 = i + 2 < data.length ? data[i + 2] : 0;
        result += base64Map[b1 >> 2];
        result += base64Map[((b1 & 3) << 4) | (b2 >> 4)];
        result += base64Map[((b2 & 15) << 2) | (b3 >> 6)];
        result += base64Map[b3 & 63];
    }
    return result;
}

Einbettung in Confluence

HTML+JS über Confluence-Makros einfügen. Keine Backend-Abhängigkeit – Rendering erfolgt im Browser über PlantUMLs öffentlichen Server. Für Enterprise-Setups lokalen PlantUML-Server nutzen.

Wichtige Vorteile:

• Interaktivität ohne Artefaktwechsel.
• Komplexe Logik durch Preprocessing.
• Minimale Ressourcen: HTML, JS, PlantUML-API.
• Confluence-kompatibel.

Implementierungsbeschränkungen

• URL-Länge bei Hex-Kodierung.
• Abhängigkeit von externem PlantUML-Server (durch lokale Bereitstellung lösbar).
• PlantUML-Preprocessor-Grenzen: Keine komplexen Berechnungen, nur Basisoperationen.

| Methode | Max. Textgröße | Komplexität |

|-----------|---------------------|-------------|

| Hex | ~2000 Zeichen | Niedrig |

| Deflate | ~50.000+ Zeichen | Hoch |

Wichtige Erkenntnisse

• PlantUML-Preprocessing ermöglicht !if-Bedingungen und Variablen für dynamische Diagramme.
• HTML+JS-Schalter aktualisieren Diagramme in Echtzeit.
• PlantUML-API erzeugt PNGs aus kodierten URLs ohne Backend-Code.
• Hex für einfache Fälle; Deflate für große Diagramme.
• Lösung läuft in Confluence ohne VPN-Probleme.

— Editorial Team