PlantUML dynamic diagrams with conditions

Dynamic Sequence Diagrams in PlantUML: Variables and Conditions

PlantUML supports preprocessing with variables and conditions, enabling dynamic sequence diagrams. Users can control detail levels with toggles, showing or hiding nested logic without creating separate artifacts.

Consider documenting an API endpoint for creating orders that triggers dozens of internal checks. A full diagram becomes unwieldy, and switching between multiple static versions is inefficient.

Preparing the Diagram Text

The base diagram text is enhanced with variables and conditions. Here's an example:

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

Variables $aliceThoughts and $bobThoughts control block visibility. The PlantUML preprocessor evaluates conditions during rendering.

HTML Interface for Controls

Toggles are built with HTML forms and JavaScript. Users select detail levels, and the code dynamically updates the diagram text and generates the image.

<form>
  <label for="aliceThoughts">Show Alice's thoughts:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">No</option>
    <option value="yes">Yes</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Show Bob's thoughts:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">No</option>
    <option value="yes">Yes</option>
  </select>
</form>

JavaScript listens for changes in select elements, injects values into the PlantUML template, and calls the encoder to generate a URL.

Encoding Text for PlantUML API

PlantUML offers an HTTP API for rendering: https://www.plantuml.com/plantuml/png/<encoded_text>. It supports PNG and SVG formats.

Simple Method (Hex)

Converts UTF-8 text to hex with a ~h prefix:

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 for short diagrams. Limitation: URL length (around 8KB).

Advanced Method (Deflate + Custom Base64)

• Deflate compression.
• Encoding in PlantUML base64: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Handles large diagrams via 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;
}

Embedding in Confluence

Insert HTML+JS via Confluence macros. No backend dependency—rendering happens in the browser via PlantUML's public server. For enterprise setups, use a local PlantUML server.

Key Benefits:

• Interactivity without switching artifacts.
• Complex logic via preprocessing.
• Minimal resources: HTML, JS, PlantUML API.
• Confluence-compatible.

Implementation Limitations

• URL length for hex encoding.
• Reliance on external PlantUML server (solved with local deployment).
• PlantUML preprocessor limits: no complex computations, just basic operations.

| Method | Max Text Size | Complexity |

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

| Hex | ~2000 characters | Low |

| Deflate | ~50k+ characters | High |

Key Takeaways

• PlantUML preprocessing enables !if conditions and variables for dynamic diagrams.
• HTML+JS toggles update diagrams in real time.
• PlantUML API generates PNGs from encoded URLs without backend code.
• Hex works for simple cases; deflate for large diagrams.
• Solution runs in Confluence without VPN issues.

— Editorial Team