PlantUML Macro
![]() | Macro and API to generate diagram images using PlantUML |
Type | JAR |
Category | Macro |
Developed by | Maxime Sinclair, Vincent Massol, Dennis Pashutkin |
Active Installs | 60 |
Rating | |
License | GNU Lesser General Public License 2.1 |
Table of contents
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
Name | Optional | Allowed values | Default value | Description |
---|---|---|---|---|
type | yes | plantuml, ditaa, dot, jcckit, salt, mindmap, regex, gantt, chronology, wbs, ebnf, json, yaml | Defined in the content (see above) | PlantUML Macro 2.3.0+ Defines the type of diagram when it's not specified in the content. When the type is defined in the content, it takes precedence over the parameter |
format | yes | png, svg or txt | png unless configured in xwiki.properties | PlantUML Macro 2.4+ Indicate the diagram output format. Motivation of using SVG format:
|
title | yes | String | No title or the title defined in the content | PlantUML Macro 2.3.1+ Sets the diagram title when it's not specified in the content. When the title is defined in the content, it takes precedence over the parameter |
server | yes | A URL to a PlantUML server | See below in the Configuration section | Overrides the location of the PlantUML server, when defined. |
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 Macro 2.0+
The PlantUML server configuration is accessible from xwiki.properties by setting the plantuml.server property. For example:
plantuml.server=http://www.plantuml.com/plantuml
It's also accessible from the Admin UI by installing the PlantUML Administration Application.
It's also possible to override the PlantUML server to use when using the macro by using the server parameter, as in:
{{plantuml server="http://www.plantuml.com/plantuml"}}
content here...
{{/plantuml}}
If a PlantUML server is specified in the Admin UI, then you can force not using any server at the level of the macro by specifying an empty server parameter, as in:
{{plantuml server=""}}
content here...
{{/plantuml}}
PlantUML Macro 2.4+
The default PlantUML diagram output format can be configured in xwiki.properties by setting the plantuml.format property. Supported values are svg, png and txt. For example:
plantuml.format=svg
The macro parameter format overrides xwiki configuration property.
The png output format is used by default if neither plantuml.format configuration property nor format macro parameter is specified.
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.
If you were using version 1.1, note that the PlantUML server configuration location has changed, see above.
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