PlantUML dynamické diagramy s podmínkami

Dynamické sekvenční diagramy v PlantUML: implementace s proměnnými a podmínkami

PlantUML podporuje předzpracování s proměnnými a podmínkami, což umožňuje vytvářet dynamické sekvenční diagramy. Uživatel může řídit úroveň detailu pomocí přepínačů, skrývat nebo zobrazovat vnořenou logiku bez nutnosti vytvářet samostatné artefakty.

Uvažujme úkol dokumentace API metody pro vytvoření objednávky, která volá desítky interních kontrol. Úplný diagram se stává objemným a navigace mezi několika statickými variantami je neefektivní.

Příprava textu diagramu

Základní text diagramu je rozšířen o proměnné a podmínky. Příklad:

participant Bob as b
participant Alice as a

!$aliceThoughts = "Ne"
!$bobThoughts = "Ne"

b -> a: Ahoj!

!if ($aliceThoughts == "Ano")
activate a
a->a: Ach bože, napsal mi!
a->a: Co dělat, jak být..
create participant Lisa as l
a -> l: Bob mi napsal, jak být?
activate l
l -> a: Prostě mu odpověz, Bože
deactivate l
!endif

a->b: Ahoj!
deactivate a

!if ($bobThoughts == "Ano")
activate b
b->b: Odpověděla o_O
!endif

b->a: Ehm... Jak se máš?
deactivate b

Proměnné $aliceThoughts a $bobThoughts kontrolují zobrazení bloků. PlantUML předprocesor vyhodnocuje podmínky při vykreslování.

HTML rozhraní pro řízení

Přepínače jsou implementovány pomocí HTML formulářů s JavaScriptem. Uživatel vybere úroveň detailu, kód dynamicky aktualizuje text diagramu a generuje obraz.

<form>
  <label for="aliceThoughts">Zobrazit myšlenky Alice:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">Ne</option>
    <option value="yes">Ano</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Zobrazit myšlenky Boba:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">Ne</option>
    <option value="yes">Ano</option>
  </select>
</form>

JavaScript sleduje změny select elementů, dosazuje hodnoty do šablony PlantUML a volá enkodér pro generování URL.

Kódování textu pro PlantUML API

PlantUML poskytuje HTTP API pro vykreslování: https://www.plantuml.com/plantuml/png/<encoded_text>. Podporovány jsou formáty PNG, SVG.

Jednoduchá metoda (hex)

Převádí UTF-8 text na hex s prefixem ~h:

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}`;
}

Vhodné pro krátké diagramy. Omezení – délka URL (asi 8KB).

Složitá metoda (deflate + vlastní base64)

• Komprese deflate.
• Kódování do PlantUML base64: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Umožňuje zpracovávat velké diagramy díky kompresi.

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;
}

Umístění v Confluence

HTML+JS je vloženo přes makro Confluence. Žádná závislost na backend – vykreslování probíhá v prohlížeči přes veřejný server PlantUML. Pro korporátní prostředí se doporučuje lokální PlantUML server.

Výhody přístupu:

• Interaktivita bez navigace mezi artefakty.
• Podpora složité logiky přes předzpracování.
• Minimální zdroje: HTML, JS, PlantUML API.
• Kompatibilita s Confluence.

Omezení implementace

• Délka URL pro hex kódování.
• Závislost na externím PlantUML serveru (řešeno lokálním nasazením).
• Omezení předprocesoru PlantUML: žádné složité výpočty, pouze základní operace.

| Metoda | Maximální velikost textu | Složitost |

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

| Hex | ~2000 znaků | Nízká |

| Deflate | ~50k+ znaků | Vysoká |

Co je důležité

• PlantUML předzpracování umožňuje podmínky !if a proměnné pro dynamiku.
• HTML+JS přepínače aktualizují diagram v reálném čase.
• API PlantUML generuje PNG podle kódovaného URL bez backend.
• Hex je vhodné pro jednoduché případy, deflate pro velké diagramy.
• Řešení funguje v Confluence bez VPN závislostí.

— Editorial Team