Diagramas dinámicos de PlantUML con condiciones

# Diagramas de Secuencia Dinámicos en PlantUML: Variables y Condiciones

PlantUML permite el preprocesamiento con variables y condiciones, lo que habilita diagramas de secuencia dinámicos. Los usuarios pueden controlar los niveles de detalle con interruptores, mostrando u ocultando lógica anidada sin necesidad de crear artefactos separados.

Imagina documentar un endpoint de API para crear pedidos que activa docenas de verificaciones internas. Un diagrama completo se vuelve inmanejable, y cambiar entre múltiples versiones estáticas es ineficiente.

Preparando el Texto del Diagrama

El texto base del diagrama se enriquece con variables y condiciones. Aquí un ejemplo:

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

Las variables $aliceThoughts y $bobThoughts controlan la visibilidad de los bloques. El preprocesador de PlantUML evalúa las condiciones durante el renderizado.

Interfaz HTML para Controles

Los interruptores se construyen con formularios HTML y JavaScript. Los usuarios seleccionan niveles de detalle, y el código actualiza dinámicamente el texto del diagrama y genera la imagen.

<form>
  <label for="aliceThoughts">Mostrar pensamientos de Alice:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">No</option>
    <option value="yes">Sí</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Mostrar pensamientos de Bob:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">No</option>
    <option value="yes">Sí</option>
  </select>
</form>

JavaScript escucha cambios en los elementos select, inyecta valores en la plantilla de PlantUML y llama al codificador para generar una URL.

Codificando Texto para la API de PlantUML

PlantUML ofrece una API HTTP para renderizado: https://www.plantuml.com/plantuml/png/<encoded_text>. Soporta formatos PNG y SVG.

Método Simple (Hexadecimal)

Convierte texto UTF-8 a hexadecimal con prefijo ~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}`;
}

Ideal para diagramas cortos. Limitación: longitud de URL (alrededor de 8KB).

Método Avanzado (Deflate + Base64 Personalizado)

• Compresión Deflate.
• Codificación en base64 de PlantUML: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Maneja diagramas grandes mediante compresión.

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

Integración en Confluence

Inserta HTML+JS mediante macros de Confluence. Sin dependencias de backend: el renderizado ocurre en el navegador vía el servidor público de PlantUML. Para entornos empresariales, usa un servidor PlantUML local.

Beneficios Clave:

• Interactividad sin cambiar artefactos.
• Lógica compleja vía preprocesamiento.
• Recursos mínimos: HTML, JS, API de PlantUML.
• Compatible con Confluence.

Limitaciones de Implementación

• Longitud de URL para codificación hexadecimal.
• Dependencia de servidor PlantUML externo (solucionado con despliegue local).
• Límites del preprocesador de PlantUML: sin cálculos complejos, solo operaciones básicas.

| Método | Tamaño Máx. Texto | Complejidad |

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

| Hex | ~2000 caracteres | Baja |

| Deflate | ~50k+ caracteres | Alta |

Lecciones Clave

• El preprocesamiento de PlantUML habilita condiciones !if y variables para diagramas dinámicos.
• Interruptores HTML+JS actualizan diagramas en tiempo real.
• La API de PlantUML genera PNG desde URLs codificadas sin código backend.
• Hex funciona para casos simples; deflate para diagramas grandes.
• La solución corre en Confluence sin problemas de VPN.

— Editorial Team