GraphvizPlugin

Draw graphs using the GraphViz utility

GraphViz is a way of representing structural information as diagrams of abstract graphs and networks. Automatic graph drawing has many important applications in software engineering, database and web design, networking, and in visual interfaces for many other domains.

This plugin uses Graphviz's applications to create an image of a directed graph. The directed graph is described using a simple text markup called "The DOT Language". This markup is written between <graphviz> and </graphviz> tags or using the %GRAPHVIZ macro. By default, an svg image attachment is created and displayed inline, replacing the <graphviz> markup.

Visit the Graphviz gallery to see some examples on what can be achieved with this plugin and Graphviz.

Full documentation is available at https://graphviz.org/documentation.

Usage

There are two ways to specify a graph:

1. using the <graphviz> xml tag
2. using the %GRAPHVIZ Foswiki macro

Both can be used to generate a graph inline, that is by specifying the DOT language as part of the page. Below examples are mostly equivalent:

<graphviz renderer="dot" type="png">
digraph G {Hello[fontcolor="red"]; Hello->World}
</graphviz>

%GRAPHVIZ{
   "digraph G {Hello[fontcolor=\"red\"]; Hello->World}" 
   renderer="dot"
   type="png"
}%

Both should render as

when installed.

The <graphviz> xml syntax has got the advantage of being in line with other wikis, such as dokuwiki. Also, the DOT code does not have to escape any double-quotes (") as is the case using the Foswiki macro way. However using a proper %GRAPHVIZ macro has got the advantage of being well integrated into Foswiki's Topic Markup Language. For instance it can be properly escaped when in a FormattedSearch.

For compatibility with DirectedGraphPlugin you may use <dot> instead of <graphviz>.

Syntax

<graphviz [params]> ... DOT code ... <graphviz>

%GRAPHVIZ{" ... DOT code ... " [params]}%

Parameter	Description	Default
DOT code	this is the graph specified in the graph description language
type="png|jpeg|gif|svg|svgz|pdf"	output format	svg
renderer="dot|neato|twopi|circle|fdp|sfdp|patchwork"	rendering engine	dot
topic="[web.]topic"	specify the topic where to store the graph image	current topic
file="..."	filename to be generated	random based on content
attachment=" ... "	attachment that may hold a .gv graph file (only available in %GRAPHVIZ)
section=" ... "	named section in topic that holds a graph description (only available in %GRAPHVIZ)
library="[web.]topic"	specify the topic where to search for images to be used in the dot graph	topic
inline="on|off"	boolean flag to specify the way how to add an svg result to the html page; if inline="on" then an <svg> html tag is generated; otherwise an html <img ... > tag is used; note that for properly linking URLs in the graphviz graph you will need to switch this on	off
expand="on|off"	boolean flag, when switched on, will expand TML macros in the DOT code before rendering it	off
style=" ... "	css styles to be added to the output
width=" ... "	width of the image result
height=" ... "	height of the image result

Graphviz from Table

Instead of having to learn the dot language, nodes and edges can also be specified in Foswiki tables:

Node	Attributes
hello	color="red"
world	shape=box

Source	Label	Target	Attributes
hello		world

Given these two tables where the only two tables in a topic then this would render the appropriate graph:

%GRAPHVIZ{
   topic="SomeTopic"

   nodestable="0" 
   nodecol="0"
   nodeattrcol="1"

   edgestable="1"
   sourcecol="0"
   labelcol="1"
   targetcol="2"
   edgeattrcol="3"
}%

Parameter	Description	Default
table="int" / edgestable="int"	index of table in topic to extract edges from
nodestable="int"	index of table in topic to extract nodes from
nodecol="int"	index of column that holds the node name	0
nodeattrcol="int"	index of colum that holds node attributs
sourcecol="int"	index of the colum holding the source node name	0
targetcol="int"	index of the colum holding the target node name	1
labelcol="int"	index of column holding the edge label
edgeattrcol="int"	index of column holding the edge attributes
preamble=" ... "	some dot code to be added before the generated node and edge code

Examples

Example 1

%GRAPHVIZ{ section="example1" main_init_label="high priority" main_printf_label="low priority" }%

Example 2

%GRAPHVIZ{attachment="softmaint.txt" renderer="neato" style="width:99%;height:auto"}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Digest::MD5	>=0	Required
File::Path	>=0	Required
File::Temp	>=0	Required
graphviz	>=0	Required
msttcorefonts		Optional

Change History

11 Jun 2018:	added file parameter to explicitly specify an output file
20 Nov 2017:	fixed error in table parser (Foswiki:Main/BramVanOosterhout)
30 Nov 2016:	missing SvgFormat parameter; fixed encoding of created dot file
02 Mar 2016:	fixed error on dot command format; improved error reporting
07 Oct 2015:	compatibility with foswiki >= 2.0.2
31 Aug 2015:	first final release
11 Aug 2015:	release of first beta
10 Aug 2015:	initial rewrite of DirectedGraphPlugin