Macro and API to generate diagram images using PlantUML

Description

This macro permits to easily generate various diagram types from a textual definition inside a wiki page, using PlantUML.

Usage

{{plantuml}}
content here...
{{/plantuml}}

The content of the macro can refer to any of the following diagram types supported by PlantUML:

• PlantUML (diagrams starting with @startuml and ending with @enduml)
• DITAA (diagrams starting with @startditaa and ending with @endditaa)
• GraphViz (diagrams starting with @startdot and ending with @enddot)
• JCCKIT (diagrams starting with @startjcckit and ending with @endjcckit)
• Salt (diagrams starting with @startsalt and ending with @endsalt)
• Mind maps (diagrams starting with @startmindmap and ending with @endmindmap)
• Regexes (diagrams starting with @startregex and ending with @endregex)
• Gantt (diagrams starting with @startgantt and ending with @endgantt)
• Chronology (diagrams starting with @startchronology and ending with @endchronology)
• Work breakdown structures (diagrams starting with @startwbs and ending with @endwbs)
• EBNF (diagrams starting with @startebnf and ending with @endebnf)
• JSON (diagrams starting with @startjson and ending with @endjson)
• YAML (diagrams starting with @startyaml and ending with @endyaml)

For more detail see the description of the PlantUML language.

Parameters definition

Examples

Use Case Diagram

{{plantuml}}
@startuml
:Customer: -> (Withdraw)
note right of (Withdraw) : This is an example.
@enduml
{{/plantuml}}

Generates:

Class Diagram

{{plantuml}}
@startuml
package "Classic Collections" #DDDDDD {
  Object <|-- ArrayList
}

package net.sourceforge.plantuml {
  Object <|-- Demo1
  Demo1 *- Demo2
}
@enduml
{{/plantuml}}

Generates:

Ditaa Diagram

{{plantuml}}
@startditaa
 Web Browser         JEE Server
 /--------\         +---------+     Database
 +--------+         |c789     |      +---+
 |c1FF    |<------->|  XWIKI  |<-=-->|{s}|
 |  Wiki  |  text   |         |      +---+
 |  page  |         +---------+
 |  with  |         |c789     |      +---+
 |diagrams|<------->|PlantUML |<-=-->|{o}|
 |        |  image  |   Server|      +---+
 \--------/         +---------+     Graphviz
@endditaa
{{/plantuml}}

Generates:

PlantUML Diagram in SVG format

{{plantuml format="svg"}}
@startuml
title [[https://rendering.xwiki.org/xwiki/bin/view/Main/WebHome XWiki Rendering]] General Architecture

skinparam component {
    style rectangle
    roundCorner 20
}

file "Input Syntax" as Input
note bottom of Input 
    Examples:
    - XWiki 2.0 Syntax
    - (X)HTML
    - MediaWiki Syntax
end note

component Parser [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/parser/Parser.java Parser]]
]

component Transformations [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/transformation/Transformation.java Transformations]]
    (optional)
]

component Renderer [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/renderer/Renderer.java Renderer]]
]

file Output
note bottom of Output
    Examples:
    - XHTML
    - XWiki 2.0 Syntax
end note

Input -> Parser
Parser -> Transformations : [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/block/XDOM.java XDOM]]
Transformations -> Renderer : XDOM'
Renderer -> Output

@enduml
{{/plantuml}}

Generates:

Configuration

It works out of the box with all the different kinds of diagrams, using the PlantUML server available on the internet. You can also configure the macro to use your own PlantUML server that you can install on the web container used by your XWiki installation (for example). Once installed, internet access is not necessary. Another option is to leave the PlantUML server field empty, in which case the macro will use PlantUML in embedded mode (you'll then need to have GraphViz installed to generate all diagrams except for the Sequence one).

plantuml.server=http://www.plantuml.com/plantuml

{{plantuml server="http://www.plantuml.com/plantuml"}}
content here...
{{/plantuml}}

{{plantuml server=""}}
content here...
{{/plantuml}}

plantuml.format=svg

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Release Notes

v2.4

v2.3.2

Fix source URL

v2.3.1

v2.3.0

v2.2.0

v2.1.1

v2.1

v2.0.2

v2.0.1

And also make it possible to upgrade from versions 1.x using the Extension Manager (without having to uninstall v1.x first).

v2.0

v1.1

If a previous version is installed, remove it before installing this new one.

With the new include parameter, you can include the content of the specified page at the begining of the macro content. It's similar to the !include directive of PlantUML http://plantuml.sourceforge.net/preprocessing.html
It is very useful to locate skin directives in an unique place.

v1.0

If a previous version is installed, remove it before installing this new one.

The macro works out of the box with all the different kinds of UML diagrams, using the PlantUML server available on the internet. But you can configure the macro to use your own PlantUML server.
An embedded version of PlantUML server is also available. To use it, just leave empty the Server configuration entry.

Diagrams larger than the page are now resized to avoid the horizontal scrollbar.

v0.7

v0.6

Initial version.

Dependencies

Dependencies for this extension (org.xwiki.contrib.plantuml:macro-plantuml-macro 2.4):

• org.xwiki.commons:xwiki-commons-component-api 12.10
• org.xwiki.commons:xwiki-commons-script 12.10
• net.sourceforge.plantuml:plantuml 1.2025.2
• org.xwiki.rendering:xwiki-rendering-transformation-macro 12.10
• org.xwiki.platform:xwiki-platform-rendering-async-default 12.10
• org.apache.httpcomponents.client5:httpclient5 5.1
• org.xwiki.platform:xwiki-platform-configuration-default 12.10
• org.xwiki.platform:xwiki-platform-resource-temporary 12.10