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

%STARTSECTION{"example1"}%
digraph G {
 node [fontname=Verdana,
       fontsize=12,
       style=filled,
       fillcolor="#EEEEEE",
       color="#EEEEEE"]

 edge [fontname=Verdana,
       fontsize=10,
       color="#31CEF0"]

 main [shape=box, color=deeppink]
 init [shape=box, color=deeppink]

 main -> parse -> execute [weight=8]

 main -> init [taillabel="%main_init_label{default=""}%",
               labelangle=-20,
               labeldistance=7,
               color=deeppink, 
               arrowhead=vee, 
               arrowtail=vee]

 main -> cleanup
 main -> printf [taillabel="%main_printf_label{default=""}%",
               labelangle=15,
               labeldistance=7]

 execute -> make_string
 execute -> printf 
 init -> make_string
 execute -> compare
}
%ENDSECTION{"example1"}%

Example 2

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

NameVersionDescription
Digest::MD5>=0Required
File::Path>=0Required
File::Temp>=0Required
graphviz>=0Required
msttcorefontsOptional

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

PackageForm edit

Author Michael Daum
Version 1.11
Release %$RELEASE%
Description Draw graphs using the GraphViz utility
Repository https://github.com/foswiki/GraphvizPlugin
Copyright © 2015-2024 Michael Daum
License GPL (Gnu General Public License)
Home Foswiki:Extensions/GraphvizPlugin
Support Foswiki:Support/GraphvizPlugin
Topic revision: r4 - 19 Jan 2024, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback