Graphviz is a program/language that allows the creation of numerous types of graphs. This extension allows the embedding of graphviz markup in MediaWiki pages and generates inline images to display.

Mscgen is a small program that parses Message Sequence Chart descriptions. Unlike Graphviz, this program does no clever layout operations or spline routing as this is not needed.
Automatic graph drawing has many important applications in software engineering, database and web design, networking, and in visual interfaces for many other domains.
You can use the provided language (e.g. dot) and create graphs with that within the wiki. There are also some other extensions that provide other interfaces for individual solutions.

[edit] Features

works out of the box for many Windows/Linux Systems (graphviz has to be in the right path)
additional support for mscgen
supports multiple graphs on one page
supports wiki-links in graphs
allows pruning of old images

[edit] Contributions

In 2004 the User Coffman created an extension to mediawiki in response to a basic need : Render Graphs online.
He found the utility Graphviz on another wiki, and thought about adopting it to mediawiki (the wiki he actually used). Exploring the Graphviz tool he discovered an incredible tool to making Graphs.
Later on many people improved the extension on their own or provided little bugfixes as snippets on the dicussion page. This led to several functional solutions for different use cases and to a bit of chaos.
Now (Fall 2010) I, (Thomas Hummel), tried to merge the most common solutions so that we finally have another working solution for several OSes in one file. As I am not that well known to PHP, there might be several long-winded or impractical lines of code - feel free to send me your improvements or comments (Discussion-Page, Message or whatever).
I started with the "improved version" from an unknown Coder and tried to fix some things on my own and then included parts of the code of other "improvements" and standalone solutions. Good sources were for example Extension:GraphVizAndMSCGen by Matthewpearson and the Extension by Gregory Szorc where I got the autopruning from.

[edit] Install Instructions

[edit] Graphviz

First of all you need at least one of the external tools "Graphviz" or "MscGen" that renders your Graph.
1. Windows: Get your copy here: http://www.graphviz.org/Download.php or here http://www.mcternan.me.uk/mscgen/
2. Unix: Same links as for windows but normally it should be preinstalled (at least graphviz - search for dot) or can be found in the package manager.
3. See Alternatives first, if you want to decide which Extension to use
Then Copy the Code found here /Graphviz.php into a file called Graphviz.php and and place it in $IP/extensions/Graphviz.php. ##Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.
1. On Ubuntu 10.10 an earlier version of the Graphviz-Extension has been added to the default (see also Manual:Running_MediaWiki_on_Ubuntu) - although this is a very old version, so you'd better replace it with the one provided here.
Add these lines to LocalSettings.php:

include("extensions/Graphviz.php"); //includes the extension

$wgGraphVizSettings->execPath = "/path/to/graphviz/"; //Path to the Graphviz Installation

Windows Default: "C:/Program Files/Graphviz/bin/" (without dot.exe) or "C:\\Program Files\\Graphviz\\bin\\"

Other Platform : "/usr/bin/" or "/usr/local/bin/" (where the dot binary is)

Make sure that write permissions for the "$IP/images" directory are granted.
Make sure that internet users get read/execute access on your executables if you use server installations. (esp. under windows)

[edit] MscGen

The same procedure as with Graphviz - the path to MscGen has to be provided in the LocalSettings.php.

$wgGraphVizSettings->MscgenPath = "/usr/bin/";

[edit] Differences to previous versions

The varable $dotCommand that points only to the dot executable is replaced (like in Extension:GraphVizAndMSCGen) with $execPath and $mscgenPath that let you choose between several renderers.

[edit] Configuration

There are some additional configuration parameters that help you to define a basic behaviour of the extension. If you don't use these parameters they contain a default value that leads to a (hopefully) good usage of the extension. For each parameter add the line $wgGraphVizSettings->ParameterName in your LocalSettings.php after the include("extensions/Graphviz.php");-line.

Parameter	Default Value	Values	Description
execPath	"C:/Program Files/ATT/Graphviz/bin/"		(Windows) Path to the GraphViz executables with the dot.exe, circo.exe, fpdp.exe, neato.exe, twopi.exe
execPath	"/usr/bin/"		(Unix/linux) Path to the Graphviz executables (mainly it points to /usr/bin/ or to /usr/local/bin/) or you use $DOT_PATH
mscgenPath	-none-		Path to the MscGen-Installation
outputType	png	see #Renderers	Which image format do you want to produce?
imageFormatting	true	true, false	Do you want to define position, border or thumb for the image (not fully supported see here)
named	named	named, md5, sha1	How are the images and imagemaps named on your drive? (see #Naming of the Images)
info	false	true, false	Adds information about the parameters given, e.g. renderers used, for use on the wiki-page. Probably most useful for debugging.
install	false	true, false	Gets you an errormessage if something fails, but maybe ruins your wiki's look. This message is in English, always. (not well implemented actually)
pruneEnabled	false	true, false	Do you want an automated pruning procedure each time you render a new graph?
pruneStrategy	filenumber	filenumber, filesize	Do you want to prune if there are too many files or if they need too much disc space
pruneAmount	10000	positive number	Defines the maximum files/filesize you accept for pruneStrategy
pruneValue	0.5	0< number <=1	Defines how many files are being pruned (0.5 = 50%)

You don't need to set these values if everything works fine for you. They are used in the LocalSettings.php only for the default behaviour of all graphs in this wiki. Some parameters can be set for each individual graph (see #Renderer or #Image-Types).

[edit] Naming of the Images

There are several ways to name the graphs. Each of them has some benefits and some problems. You set the Naming-Scheme by setting $wgGraphVizSettings->named in the LocalSettings.php (See #Configuration).

Naming Type	Description	Pros/Cons	Example
named	The storagename is the name of the wikipage and the name of the graph	+ human readable + no cleanup necessary - two graphs need separate names	Graphviz_Sample---digraph+NAME.png
md5	name of your graph is based on a md5 hash of its source	+ don't worry about graphnames + pretty fast hash - permanent cleanup necesary (manually or scripted) md5 is buggy - possibility that 2 graphs have the same hash but are not the same	Graphviz_Sample---0a1e0c6bb9c6d3af6486d8f3de657f0f.png
sha1	name of your graph is based on a SHA1 hash of its source	+ don't worry about graphnamesbr/> + no hash-bug as md5 - permanent cleanup necessary (manually or scripted) - not so fast as md5	Graphviz_Sample---a3862ef7e7f889778f0259657b07ba985197ef88.png

[edit] Drawing Graphs

Basically you only need to write your Graph in the dot language (or any other supported language) and put it into <graphviz>dot-commands</graphviz> or <mscgen>mscgen-commands</mscgen>.
See the #Examples for some basic graphs - you don't even need the "border" or "frame"-tags.

[edit] Mscgen

Keep in mind that mscgen uses a language _similar_ to dot but it isn't really dot. So you have to write your own code for graphviz and mscgen to display the same graph. (Furthermore the goals of graphviz and mscgen are not the same)

Another limitation when using mscgen is that you can't use multiple graphs on one page (if you don't use hashed storage-names).

[edit] Multiple Graphs

This extension supports multiple graphs on one wiki-page.

If you name the pictures by the graph-names (named='named') you only have to name the graphs different. That means that the following two graphs can be put together on on page.

First Graph	Second Graph
`<graphviz>` `graph NAME {... } </graphviz>`	`<graphviz> graph ANOTHERNAME {... } </graphviz>`

This doesn't work for mscgen-Graphs, because custom names aren't supported. But you can put one mscgen-Graph and multiple graphviz-graphs on one page.

If your pictures are named with md5- or sha1-hashes then you can have multiple graphs of each type (graphviz and/or mscgen) on your page. Keep in mind that you should clean up your image-directory from time to time, because the hash changes when the code has been modified. (See #Naming of the images)

[edit] Wiki-Links

In dot you can define an URL for each node. This ist normally done before defining the graph. See #Example3 for an example with Wiki-Links.

In case you need an external URL you write:

Mollusca [URL="http://www.mollusca.animal"];

And for an internal link in your wiki you write:

Mollusca [URL="Mollusca"];

That's all.

[edit] Wiki-Style

In case you want to put some kind of structure into your page you can use some Image-Attributes like for any other image (orientated on MediaWiki-Syntax like here: w:Extended_image_syntax).
The attributes are used like html-attributes. (e.g. <graphviz caption="Hello World">...dot...</graphviz>)

Attribute	Description	Value
caption	Adds a caption to the graph (if bordered or thumbed)	some string
alt	Alternative text for graph (if not set caption is used and at least a default string)	some string
border	Adds a border around the graph	frame, border
location	Defines the position of the graph	left, middle, center, right, none
alignment	Vertical alignment to the text	baseline, middle, sub, super, text-top, text-bottom, top, bottom
type	Several changes in design	frame, framed, thumb, thumbmail, frameless

Please bear in mind that those features are not fully equal to the "original" image-attributes of the mediawiki-image-attributes.
Differences/inconsistences are:

In case of thumbed images the image-map isn't scaled down, so it won't fit anymore
In case of thumbed images, they do not link to an image-page with a further description of the license and the picture in a higher resolution - we only add a (+)-sign to the caption with the direct link to the image.
a framed and centered image will have a border with a width of 100%

Alternative: You could link to your images directly if you want to. So you could put the graph into <div style="visibility:none;"><graphviz>...</graphviz></div> and put the image of the graph anywhere into your page (or in any other page) via the img-tag.

If you use the named='named'-setting the graph names won't change and can be used easily.
You have to allow linking to external images (since the images are not in the db) (and you can restrict it to your domain for security)
you cannot use imagemaps that easy

[edit] Renderer

This extension can handle two applications for graph-drawing: Graphviz and Mscgen.
Graphviz comes with several rendering engines and Mscgen has its own. For each use case another renderer is best, because the position of the nodes is found with other algorithms.
More information on the graphviz-renderers (with images) can be found on graphviz.org and for mscgen on http://www.mcternan.me.uk/mscgen/.

Renderer	Description
dot	typical hierachical layout with a "start" and an "end"
neato	"spring model" layout
fdp	like neato but better for lager graphs
sfdp	fdp multicsale version
circo	circular layour like for telecommunication networks
twopi	radial layout with "start" in the middle
mscgen	message sequence charts

You can define a renderer as default (-> #Configuration) or add it to the individual graph with an attribute (-> <graphviz renderer='neato'>...dot...</graphviz>).

[edit] Image-Types

Graphviz and Mscgen can produce a huge amount of different image types (see more on the particular site). The Graphviz-Extension supports only the ones that seem kind of useful for the use in a wiki.

Graphviz: bmp, gif, jpg, jpeg, png, svg, svgz
Mscgen: png, svg

Note: To display vector-graphics you have to configure your wiki installation properly (-> SVG)

You can define an image type as default (-> #Configuration) or add it to the individual graph with an attribute (-> <graphviz outputType='jpg'>...dot...</graphviz>).

[edit] Examples

For a start you can try these Examples:

Example 1

"Hello World"-graph for the Example no. 1

<graphviz border='frame' format='png'>
 digraph example1 {Hello->World!}
</graphviz>

Example 2

Example No.2 rendered with neato

<graphviz renderer='neato' caption='Hello Neato'>
graph EXAMPLE2 {
   run -- intr;
   intr -- runbl;
   runbl -- run;
   run -- kernel;
   kernel -- zombie;
   kernel -- sleep;
   kernel -- runmem;
   sleep -- swap;
   swap -- runswap;
   runswap -- new;
   runswap -- runmem;
   new -- runmem;
   sleep -- runmem;
}
</graphviz>

Example 3

A more complex graph as defined by Example No. 3 (original imagemap contains (Wiki-)Links)

<graphviz caption='Hello SVG and PNG' alt='phylogenetic tree' format='png'>
digraph G {
                node [shape=plaintext];
                Mollusca [URL="Mollusca"];
                Neomeniomorpha [URL="Neomeniomorpha"];
                X1 [shape=point,label=""];
                Caudofoveata [URL="Caudofoveata"];
                Testaria [URL="Testaria"];
                Polyplacophora [URL="Polyplacophora"];
                Conchifera [URL="Conchifera"];
                Tryblidiida [URL="Tryblidiida"];
                Ganglioneura [URL="Ganglioneura"];
                Bivalvia [URL="Bivalvia"];
                X2 [shape=point,label=""];
                X3 [shape=point,label=""];
                Scaphopoda [URL="Scaphopoda"];
                Cephalopoda [URL="Cephalopoda"];
                Gastropoda [URL="Gastropoda"];
                Mollusca->X1->Testaria->Conchifera->Ganglioneura->X2->Gastropoda
                Mollusca->Neomeniomorpha
                X1->Caudofoveata
                Testaria->Polyplacophora
                Conchifera->Tryblidiida
                Ganglioneura ->Bivalvia
                X2->X3->Cephalopoda
                X3->Scaphopoda
}
</graphviz>

You can find additional Graphviz-Examples in the following flickr gallery: http://www.flickr.com/photos/kentbye/sets/72157601523153827/

[edit] Tutorials/Online-Samples

see here for actual examples in Wikis:

[edit] Pruning

Each time we create a new graph we're going to check the Image-Path for pruning. There are several options on how to prune. Configure Pruning with the adequate parameters in LocalSettings.php (see #Configuration).

With the default settings you don't need any pruning, because each graph is saved accoring to its name. If you update the Graph the image-file will be replaced so there will be no unnecessary file. Reasons for pruning can be: limited storage-space for images, renamed or removed graphs, graphs are named with a hash.

However the best solution for pruning would be to clean up the images manually from time to time or do it automatically by a cronjob. This saves much cpu-load.

[edit] Code

/Graphviz.php

[edit] Development

Since I'm not a very experienced developer it would be nice if some "experts" could review the code or improve it on some edges.
I'm also happy if you'd notify me about bugs or problems you have (e.g. on the Discussion page).

[edit] Important points

Check for Security Leaks
- especially there has been mentioned: This [former] plugin does not properly sanitize user input when generating the "named" version of the files. This can lead to clobbered files and/or more serious vulnerabilities. --Andy753421 04:54, 27 July 2010 (UTC)
- See Security for developers for specific types of vulnerabilities
Sometimes there is an error of preg_replace: "Unknown modifier '\' on line 434" - I can't find the mistake.

[edit] Things that should be done

Change the old version on the ubuntu default extensions package
What to do with graphs that are too large? e.g. for the GET-request? Maybe some attribute in the <graphviz>-Tag that this is partial code and that it waits? Or at least shortening some commands, links, ...?
using popen()/proc_open() instead of shell_exec() for php save-mode if possible

[edit] Nice to have features

add uploadDir to variables
Provide this on a svn-Server?
On my local installation a graph is rerendered very often (each hour or so) even if nothing has changed on the page. (Is this only my fault?)
- Can we reduce cpu-load with preventing graphviz to create a new image if the page hasn't changed?
- Can I then prune all images that are older than an hour? Or do proper installations use a cache that maybe lasts a week or so?
Error when setting $wgGraphVizSettings->install=true on ubuntu.
Generate Graphs without extra tools (directly in the browser): Canvas?, Base 64 Encoding see also, Extension:Graph, ...
custom shapes for nodes in Graphviz aren't supported yet (http://www.graphviz.org/Documentation/html/shapehowto.html)
improve pruning
- save pruning settings (maybe settings-file in graphviz-folder or images folder, because of write access?)
  - don't prune for each graph but only check date of last pruning
- remove files older than some date
use the image formatting with wiki syntax with the help of MW-Renderer, so that it doesn't stay hardcoded
put the generated graphs into the wiki-database, so that they can be handled like normal pictures

[edit] Alternatives

If you don't like this extension there are some others that I find remarkable (although I tried to put the main functionality of all of them into this extension - so thank them for their ideas also).

The Extension by Gregory Szorc is absolutely well coded and supports auto-pruning.
Extension:Graph This Extension lets you draw ASCII-Art, SVG, and Graphviz-Images without(?) the use of the Graphviz-Tool
Extension:FreeMind uses the FreeMind-Tool to draw graphs
Extension:Semantic_Graph also uses the FreeMind-Tool to draw (as an alternative to the #Projects based on this extension
Extension:GraphVizAndMSCGen built upon the old graphviz-source

[edit] Projects based on this extension

The "Semantic Result Formats"-Extension is used in conjunction with the Semantic MediaWiki extension, that bundles a number of further result formats for SMW's inline queries.
- Extension:Semantic Result Formats/graph_format (displays connections between pages (as graph)
- Extension:Semantic Result Formats/process_format (displays process graphs)
Extension:Collaboration_Diagram (renders and visualizes a bipartite graph of any article and its editors)

User:Hummel-riegel/GraphViz

[edit] Extension:GraphViz

[edit] Features

[edit] Contributions

Contents

[edit] Install Instructions

[edit] Graphviz

[edit] MscGen

[edit] Differences to previous versions

[edit] Configuration

[edit] Naming of the Images

[edit] Drawing Graphs

[edit] Mscgen

[edit] Multiple Graphs

[edit] Wiki-Links

[edit] Wiki-Style

[edit] Renderer

[edit] Image-Types

[edit] Examples

[edit] Tutorials/Online-Samples

[edit] Pruning

[edit] Code

[edit] Development

[edit] Important points

[edit] Things that should be done

[edit] Nice to have features

[edit] Alternatives

[edit] Projects based on this extension

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Support

Download

Development

Communication

Print/export

Toolbox