Plant UML Plugin

Draw graphs using PlantUML

Introduction

Unified Modeling Language (UML) is a standardized style of graphing and visualizing various aspects of projects, usually for project documentation. The PlantUML software provides a simplified interface for describing these different graph styles defined in UML and renders those descriptions as graphs. This simplifies the process as updates don't require readrawing an entire graph by hand.

This plugin uses the PlantUML Java application to create a UML diagram. The directed graph is described using a simple text markup based on "The dot Language" (defined for Graphviz). This markup is written between <plantuml> and </plantuml> tags. By default, a png image attachment is created and displayed inline, replacing the <plantuml> markup. Any other requested formats are saved as attachments.

Visit PlantUML to see some examples on what can be achieved with this plugin and Graphviz. Full documentation is available there.

This plugin is based on DirectedGraphPlugin and borrows from its implementation significantly, in terms of both documentation and implementation.

Caution <plantuml> syntax is not compatible with versions of Foswiki:Extensions.WysiwygPlugin prior to 28 June 2009. It is recommended that you upgrade WysiwygPlugin if you are running an older version. If that is not practical then raw editing is recommended, or use <sticky> tags to protect the plantuml tags.

Attachment Handling

This version of the plugin uses the Foswiki API to manipulate the attached graphs. The first user to view a topic containing a directed graph will be denied access if they do not have update permission. If defaults or plantuml parameters have changed, viewing the topic may modify attachments, which will require update permission.

The files generated by the <plantuml> command are cached as attachments to the topic. Any change to the <plantuml> input will result in the attachments being updated.

Each generated file is attached to the topic using the Foswiki attachment API. This results in revision control of the attached files, and updates to the topic for each generated file. If Foswiki is configured to increment a new revision for each update (See http://foswiki.org/System/ForceNewRevision and config parameter $Foswiki::cfg{ReplaceIfEditedAgainWithin} = 0 ), then every updated attachment will result in a new topic revision due to the changed metadata.

Caution The plugin will also update attached files during Preview. If the edit is subsequently cancelled, the attachments will be regenerated again.

A MD5 hash is calculated for each plantuml command input and the hash is saved in the Foswiki work_area directory. The hash file is named umlindex.xml and managed using the XMLStoreContrib extension. If the calculated hash matches on subsequent page visits, the attached graphics files are used without rerunning PlantUML. If the hash doesn't match, the attachments are regenerated.

As topics are rendered for viewing, attachments created by this plugin that are no longer needed will be removed.

If a topic is renamed, the umlindex.xml file in the workarea directory will be updated accordingly.

Also note that after changes that modify the order of generated image names, it may be necessary to refresh the browser cache with shift-reload.

Inline Graphics

The plugin will embed the generated image inline into the resulting HTML page. The inline format defaults to PNG. JPG and SVG formats are also supported.

• Regrettably, PlantUML does not support any sort of hot-linking; static images only.
• SVG images are inserted inline (by the plugin, transparently to the user) using the <object> tag.
  • A PNG image will be automatically generated and inserted as a fallback image to support older browsers without SVG support.
  • Links within the SVG file will be altered to include a target="_top" parameter to get consistent link behaviour across browsers.

Syntax Rules

Enclose the description for your directed graph within <plantuml> ... </plantuml> tags. These should be used in place of the PlantUML @startuml and @enduml tags, not in addition to them.

You can use the following parameters in the plantuml tag to control the rendering of your graph (All parameters are optional):

Parameter:	Description:	Default:
file="file_prefix"	Overrides the dynamically generated filenames. If specified, must be unique for each graph within a single topic! Suffix is still generated automatically based upon file type.	PlantUMLPlugin_nn nn increments per graph
hideattachments="on"	Set whether or not attachments should be hidden from the attachment table	on
inline="png" inlineattach="png"	Specifies the type of file to be attached inline to the page. Must be png or jpg or svg.	png
linkattachments="on"	Add links for file types other than the inline type if present	on

Examples

Examples can be found in PlantUMLPluginExamples.

Plugin Configuration

PlantUMLPlugin Global Preference Settings

*Note: Copy the below settings to your SitePreferences topic and remove the # if changes are required. These settings can be placed in SitePreferences, WebPreferences, User topics, or any individual topic.

Sample settings

   * #Set DIRECTEDGRAPHPLUGIN_DEBUG = 0
   * #Set DIRECTEDGRAPHPLUGIN_FORMATS = none
   * #Set DIRECTEDGRAPHPLUGIN_HIDEATTACHMENTS = on
   * #Set DIRECTEDGRAPHPLUGIN_INLINEATTACHMENT = png
   * #Set DIRECTEDGRAPHPLUGIN_SVGFALLBACK= png
   * #Set DIRECTEDGRAPHPLUGIN_LINKATTACHMENTS = on

Description of the settings

Changes to the settings marked will cause changes to the file hash. This will result in the attached graphcs being regenerated on the next view

All settings are prefixed with DIRECTEDGRAPHPLUGIN_ as shown above The prefix is ommited from this table to improve layout

Setting	Description	plantuml override	Default
HIDEATTACHMENTS	Set whether or not attached files should be automatically hidden in the attachments table. (n/a for direct file I/O)	hideattachments="on"	on
INLINEATTACHMENT	Set the format for inline attachment files. png, jpg or svg	inline="png"	png
SVGFALLBACK	Set a fallback image type for older browsers when SVG inline is set. Set to png or jpg	svgfallback="png"	png
LINKATTACHMENTS	Include links for other attachment types if specified. Generates links in the format of [ps], [pdf] following the inline image.	linkattachments="on"	on
DEBUG	Debug plugin: (See output in working/logs/debug.log)	[n/a]	0

Foswiki bin/configure settings

All settings start with $Foswiki::cfg{Plugins}{PlantUMLPlugin}, and on many systems, these are optional.

Standard Settings

{Enabled}	Set to 1 to enable the plugin
{plantJar}	Path to the PlantUML .jar file. By default, this is /usr/local/bin/plant.jar.

Expert settings

{Module}

Required. Set to 'Foswiki::Plugins::PlantUMLPlugin' Do not change

Plugin Installation Instructions

Installation

1. follow instructions for your distribution. Install GraphViz, PlantUML. If available, install the msttcorefonts. Also install perl modules Digest::MD5, Storable, File::Copy, File::Path, File::Spec, and File::Temp using CPAN whatever is appropriate for your distribution.
2. Use the "Extensions" tab in bin/configure Click the "Find More Extensions" button, locate the PlantUMLPlugin and click the "Install" button.
   • Alternative - manually install the plugin from the shell:
     1. Retrieve installer and the .tgz or .zip file, attached to Foswiki.org
     2. Put the installer and archive into your foswiki root directory
     3. Run the installer and follow the prompts perl PlantUMLPlugin_installer.pl
3. Using the Foswiki configure interface, set the paths to the plantuml jar file.
4. Enable the plugin in the configuration settings.

Debian/Ubuntu users

1. Install the prerequisites using apt-get
   • apt-get install graphviz
   • apt-get install msttcorefonts
2. Proceed with steps above

Reminders:

• The standard Foswiki "attach" API will be used by the plugin. View users will require "update" permission if the plugin needs to regenerate the attached files.

Verify your installation

• Ensure that the plantuml command can execute dot. From a command prompt, enter java -jar /usr/local/bin/plantuml.jar -testdot and examine the output. The output should say something like Installation seems OK. File generation OK

Dependencies:

Name	Version	Description
Foswiki::Contrib::XMLStoreContrib	>=0	Required

Package:	Description:
Graphviz	Preprocessor for drawing UML diagrams	http://graphviz.org/
PlantUML	Tool for generating UML diagrams	http://plantuml.com/
Web fonts	Fonts required for plantuml's png creations on non-Windows servers.	http://www.graphviz.org/pub/graphviz/webfonts-1.0-5.noarch.rpm

The webfonts package installs the Microsoft andalemo, arial, comic, courier, georgia, impact, times, trebuc, veranda and webdings Truetype fonts on non-Windows systems. See http://en.wikipedia.org/wiki/Core_fonts_for_the_Web for more information on the webfonts.

Plugin Info

Change History:
13 Aug 2015:	1.0.0 Initial version