%%(background:yellow;border-style:solid;)
%%center
This plugin does not work with JSPWiki 2.3.x and newer versions.\\
For an equivalent plugin, see [ImageGenGraphVizPlugin].

%%
%%
----

%%commentbox
Okay, the WorkFlowPlugin inspired me to take the time to just write this one up.  I've been wanting it for a while but never seemed to get around to it.  Feedback is welcome on GraphVizPluginDiscussion.  --JohnV
%%

This plugin reads its parameters and (re)generates a graph and image map which are attached to the specified output page, it then emits an html {{img}} tag to show the graph.  You can specify the {{output}} format (i.e. png, jpg, gif) as well.

Three files per graph are generated and attached to the target {{page}} using the {{title}} as thier file names.  (e.g. ''my-title''.png, ''my-title''.dat ''my-title''.map). The map file will not be generated if the imap parameter is '{{false}}'.

When the plugin is invoked it looks at the current page's version number and the version number
stored in the .dat file, if the numbers do not match (or the .dat file does not exist) the graph
is generated.

Generation involves spawning the 'right' graphviz executable, attaching the resulting .png (or whatever) and
.map to the output page and creating a .dat file to hold the current version number and the raw graphviz data that was used.

----
!Parameters
;{{title}}: required, the name of the graph.

;{{style}}: required, style of graph to generate 'graph' ( or 'neato'), or 'digraph ( or 'dot'), refer to GraphViz doc's.

;{{imap}}: optional, defaults to 'true', set to 'false' to not have an imap generated.

;{{page}}: optional, defaults to the current page and is the page to which the generated data files are attached.

;{{output}}: optional, defaults to 'png', what image format do you want generated?  It must be a supported output type by graphviz, and must be displayable using an html img tag. See [GraphViz Output Formats|http://www.graphviz.org/cvs/doc/info/output.html] for more.  Not all of theose are useful in this context, png, jpg, gif are the most useful of the bunch, though 'svg' is an interesting idea, but requires uses to have a plugin to display it.

;{{_body}}: required, contains the graph data, any graphviz syntax for the given style is acceptable so long as it does not contain '}]' which ends the plugin. It is up to user to make sure correct style is specified for the given graph data (A->B needs digraph (dot) , A--B needs graph (neato) as the style).


----
!Installation:
# Install GraphViz [http://www.graphviz.org/]
# Add {{graphviz.bin}} to your jspwiki.properties, pointing to where you installed it.
# Drop the GraphVizPlugin.jar in your lib


----
!Example
It really helps to know the graphviz syntax, see [http://www.graphviz.org/], specifically the [dot Guide|http://www.graphviz.org/Documentation/dotguide.pdf] and [neato Guide|http://www.graphviz.org/Documentation/neatoguide.pdf].

This example:
{{{
[[{com.mckessonaps.jspwiki.plugin.graphviz.GraphVizPlugin title='NameOfYourGraph' style='graph'

a--b--c
d--e--f
b--e
g--a
}]
}}}

Results in: [GraphVizPlugin.jpg]


----
!Cautions
If you specify {{title=foo}}, {{page=baz}} to more than one plugin invokation, this will cause 'cross-talk' and they will regenerate over each other. 

If {{imap}}='true' (the default) additional processing of the graph data is done to guess at the URL attributes to be used. If things don't turn out right, look in the .dat file to see the graph data that resulted from the processing.

I suggest the {{title}}, and {{page}} parameters always be specified using nice clean WikiNames, all bets are off if they have spaces, special chars, etc.

If you change your mind about the {{output}} format, you're stuck with the old attachments, sorry.

----
!Special Note
The string {{$(nodeAttributes)}} can be put in the body of the plugin (in your graph data) to indicate where the special node attributes created by {{imap='true'}} (the default setting) are to be placed.  If not specified the attribtues are put before your graph data.  

An example of why you might need to do this is in order. This:
{{{
[[{com.mckessonaps.jspwiki.plugin.graphviz.GraphVizPlugin title='NameOfYourGraph' 
    style='graph' output='png'

node [shape=box];

$(nodeAttributes)

a--b--c
d--e--f
b--e
g--a
}]
}}}

Results in: [GraphVizPlugin.png], if the {{$(nodeAttributes)}} bit was ommited, the output would be exactly like the first example where {{node [[shape=box];}} was not present.  This is due to how graphviz processes the data, read it's manual or ask for a more detailed explaination if you care.

----
!Discussion, over on GraphVizPluginDiscussion please.