PlantUML Macro
 | Macro and API to generate diagram images using PlantUML |
| Type | JAR |
| Category | Macro |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
This macro permits to easily add UML (or DITAA) diagrams inside a wiki page. The diagram is defined as a simple text using a special syntax. This text is automatically interpreted to produce an image of the diagram.
This macro use PlantUML, an open-source tool, as the rendering engine.
Usage
content here...
{{/plantuml}}
For more detail see the description of the PlantUML language.
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).
The PlantUML server configuration is done on the XWiki.PlantUMLMacro page.
Examples
Use Case Diagram
@startuml
:Customer: -> (Withdraw)
note right of (Withdraw) : This is an example.
@enduml
{{/plantuml}}
Generates:
Class Diagram
hide empty members
hide empty methods
package "Classic Collections" #DDDDDD {
Object <|-- ArrayList
}
package net.sourceforge.plantuml
class Demo1 {
-Number Identifier
+String Name
}
Object <|-- Demo1
Demo1 *- Demo2
end package
{{/plantuml}}
Generates:
Ditaa Diagram
@startditaa
Web Browser JEE Server
/--------\ +---------+ Database
+--------+ |c789 | +---+
|c1FF |<------->| XWIKI |<-=-->|{s}|
| Wiki | text | | +---+
| page | +---------+
| with | |c789 | +---+
|diagrams|<------->|PlantUML |<-=-->|{o}|
| | image | Server| +---+
\--------/ +---------+ Graphviz
@endditaa
{{/plantuml}}
Generates:
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.
Go to the page XWiki.PlantUMLMacro, you'll view a generated image proving the good installation of the macro and displaying the plantUML release used.
If you want to run your own instance of the PlantUML server, please follow the following steps:
- Download Graphviz and install it on the web server. It's a prerequisite for PlantUML.
- Then, you must set the GRAPHVIZ_DOT environment variable to locate the dot executable file.
- Download the PlantUML servlet War and deploy it. You can use the web container already used by XWiki.
- Finally, go to the page XWiki.PlantUMLMacro and click on the "edit this URL" link to specify the address of your PlantUML server.
Release Notes
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
Dependencies
Dependencies for this extension (org.xwiki.contrib.plantuml:macro-plantuml-macro 2.0):
- org.xwiki.commons:xwiki-commons-component-api 12.10
- org.xwiki.commons:xwiki-commons-script 12.10
- net.sourceforge.plantuml:plantuml 1.2021.7
- 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
