Diagrammes dynamiques PlantUML avec conditions

Diagrammes de séquences dynamiques en PlantUML : Variables et conditions

PlantUML prend en charge le préprocesseur avec variables et conditions, permettant de créer des diagrammes de séquences dynamiques. Les utilisateurs peuvent contrôler les niveaux de détail grâce à des interrupteurs, affichant ou masquant la logique imbriquée sans générer d'artefacts séparés.

Imaginez documenter un point d'API pour la création de commandes qui déclenche des dizaines de vérifications internes. Un diagramme complet devient vite ingérable, et basculer entre plusieurs versions statiques est inefficace.

Préparation du texte du diagramme

Le texte de base du diagramme est enrichi de variables et conditions. Voici un exemple :

participant Bob as b
participant Alice as a

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

b -> a: Salut !

!if ($aliceThoughts == "Yes")
activate a
a->a: Oh mon Dieu, il m'a écrit !
a->a: Que faire, que dire...
create participant Lisa as l
a -> l: Bob m'a écrit, qu'est-ce que je fais ?
activate l
l -> a: Réponds-lui, bon sang
deactivate l
!endif

a->b: Salut !
deactivate a

!if ($bobThoughts == "Yes")
activate b
b->b: Elle a répondu o_O
!endif

b->a: Euh... Comment ça va ?
deactivate b

Les variables $aliceThoughts et $bobThoughts contrôlent la visibilité des blocs. Le préprocesseur PlantUML évalue les conditions lors du rendu.

Interface HTML pour les contrôles

Les interrupteurs sont construits avec des formulaires HTML et JavaScript. Les utilisateurs sélectionnent les niveaux de détail, et le code met à jour dynamiquement le texte du diagramme et génère l'image.

<form>
  <label for="aliceThoughts">Afficher les pensées d'Alice :</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">Non</option>
    <option value="yes">Oui</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Afficher les pensées de Bob :</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">Non</option>
    <option value="yes">Oui</option>
  </select>
</form>

JavaScript écoute les changements dans les éléments select, injecte les valeurs dans le modèle PlantUML et appelle l'encodeur pour générer une URL.

Encodage du texte pour l'API PlantUML

PlantUML propose une API HTTP pour le rendu : https://www.plantuml.com/plantuml/png/<texte_encodé>. Elle supporte les formats PNG et SVG.

Méthode simple (Hexadécimal)

Convertit le texte UTF-8 en hexadécimal avec un préfixe ~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}`;
}

Idéal pour les diagrammes courts. Limite : longueur d'URL (environ 8 Ko).

Méthode avancée (Deflate + Base64 personnalisée)

• Compression Deflate.
• Encodage en base64 PlantUML : 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Gère les grands diagrammes grâce à la compression.

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

Intégration dans Confluence

Insérez HTML+JS via les macros Confluence. Pas de dépendance backend — le rendu se fait dans le navigateur via le serveur public PlantUML. Pour les environnements entreprise, utilisez un serveur PlantUML local.

Avantages clés :

• Interactivité sans changer d'artefact.
• Logique complexe via préprocesseur.
• Ressources minimales : HTML, JS, API PlantUML.
• Compatible Confluence.

Limites de mise en œuvre

• Longueur d'URL pour l'encodage hexadécimal.
• Dépendance au serveur PlantUML externe (résolue par déploiement local).
• Limites du préprocesseur PlantUML : pas de calculs complexes, seulement des opérations basiques.

| Méthode | Taille max du texte | Complexité |

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

| Hex | ~2000 caractères | Faible |

| Deflate | ~50k+ caractères | Élevée |

Points clés

• Le préprocesseur PlantUML permet les conditions !if et variables pour des diagrammes dynamiques.
• Les interrupteurs HTML+JS mettent à jour les diagrammes en temps réel.
• L'API PlantUML génère des PNG à partir d'URL encodées sans code backend.
• Hex pour les cas simples ; deflate pour les grands diagrammes.
• Solution fonctionnelle dans Confluence sans problèmes de VPN.

— Editorial Team