Programmatically adding PlantUML diagrams
- Boris Jockov
Developers can write scripts to programmatically add macros and attachments with PlantUML diagrams.
Adding a macro
In order to display the PlantUML diagram on a Confluence page, page needs to be parsed and plantumlcloud macro added to it.
Macro parameters:
Parameter name | Description | Mandatory |
|---|---|---|
filename | Name of the SVG attachment | Yes |
revision | Latest version of SVG attachment, in this case it is 1 | Yes |
data | URI encoded, deflated and base64 encoded diagram markup | Yes |
toolbar | bottom or none | No |
compressed | Set to true | Yes |
originalWidth | Obtained from SVG file | No |
originalHeight | Obtained from SVG file | No |
Getting SVG width and height
getSVGSize = function(svg) {
//GraphViz diagrams define size in pt, so we perform conversion to px if needed
const svgWidth = parseFloat(svg.attributes.width.value.match(/(\d+(?:\.\d+)?)[px|pt]/)) * (svg.attributes.width.value.endsWith('pt') ? 4/3 : 1);
const svgHeight = parseFloat(svg.attributes.height.value.match(/(\d+(?:\.\d+)?)[px|pt]/)) * (svg.attributes.height.value.endsWith('pt') ? 4/3 : 1);
return {width : Math.round(svgWidth), height : Math.round(svgHeight)};
};
Compressing the diagram markup
bytesToString = function(arr) {
var result = new Array(arr.length);
for (var i = 0; i < arr.length; i++) {
result[i] = String.fromCharCode(arr[i]);
}
return result.join('');
}
btoa(bytesToString(pako.deflateRaw(encodeURIComponent(data))))This example uses pako.js, a zlib compatible JavaScript library for data compression.
Example macro
<ac:structured-macro ac:name="plantumlcloud">
<ac:parameter ac:name="toolbar">bottom</ac:parameter>
<ac:parameter ac:name="filename">My FSM diagram.svg</ac:parameter>
<ac:parameter ac:name="originalHeight">913</ac:parameter>
<ac:parameter ac:name="data">pVdNb+IwEP01kbIHEIJWPfdL2sNWPbC715VxJuDi2MF2ULn0t+84CWloZtzVVgIDfs9jj+fNTMiuFj4IF5pKZ4uHbHHbjbWQe7GFbLlogtL4kd3cjXGphfc4va5BXqD4/f11h+NR6AY4UJkCXqfgbDadK5UO4PJDI0zw36Z4LQLiJicgb12g5rcQOnsEthOexebz6VywezDnFTizimj7c8o9gvPKkketIOxsQSHhVAM1r0i2t42TJJ86vCiK3LeRvOd8DnYdnDLbweTNw6USsuUyimH+JGr8mtZEhZz2giLnbIgjx8P1N/YbZLCOOF3HlDbyzmSWNriCY/XRnYlTQ0yjTyJOHg4J75iQI7KxxYkGhKMTBF4Debo+6ebZ6rE7zvj+LqnveVzZAohEVgazphQyUtYnI8VGA+feDN9/tA8mu77Lrh8YgioYoI8Lg+6sD2khRIVSiu7rDJ9UHQHdV0g6Cx3rEo7RG36FKst8IzywDFHX+pS3JY6qSUMFVIUI8OwK3J63JXXCu97GwOBSYAdy/6vWyux5Y1JbT9aGDt4mblnbLX+EtyxWdEXW2rc2AqVoNAuDc7ztqBGo0PZF+LyThLHIpZUQEQc8Zg1dNFsMxcCbHIF0KXma5N/HDLA13m46vK0i2eDEZF+HqBIfR5bXmH9lFspj+9c/RlGf7mpfLI9i207I2otjQtIpPWXLVVwPIS2ZRKg/jdgaAhevPlFw9z2c+IzGzoV41CmKlqU5qLBxJS3FW7xNXaS0WmNzHBdA2qnvscwmvbKbF7TkLxr0imWj2fDTJwjBr+GQwLEYyf1zWWIoE6wasLzTR2JvxBj0I499hb+2Ubkcx+irPYaXxFEoHXtst6nPk8qIAvtEOlvMUNwQg5ZId4pGJgWXbV+oqP9XNc/VctbUs+zmvnvSGZ5PuqegNj2RMODdohbsZT7TUAZmPblvdrUAU+Cfob8=</ac:parameter>
<ac:parameter ac:name="compressed">true</ac:parameter>
<ac:parameter ac:name="originalWidth">942</ac:parameter>
<ac:parameter ac:name="revision">1</ac:parameter>
</ac:structured-macro>Â
SVG and PNG diagram exports
The add-on relies on SVG exports for showing diagrams in Confluence pages and PNG exports for showing diagrams in PDF page exports.
Both exports must be saved as Confluence attachments on a page where the diagram resides. Naming must follow diagram naming. i.e My FSM diagram.svg and My FSM diagram.png.
For this purpose, users are instructed to start their own PlantUML server in the form of a Docker image or as Java webapp.
The add-on’s backend cannot be used for this purpose as it is protected to allow only requests originating from the add-on.