Item8241: Adding support for inline SVG output.

git-svn-id: http://svn.foswiki.org/trunk/DirectedGraphPlugin@4892 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

data/System/DirectedGraphPlugin.txt

@@ -1,7 +1,6 @@
-%META:TOPICINFO{author="ProjectContributor" date="1238965436" format="1.1" reprev="1.7" version="1.7"}%
+%META:TOPICINFO{author="ProjectContributor" date="1252207814" format="1.1" reprev="1.18" version="1.18"}%
 ---+!! Directed Graph Plugin
 
-<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
 %TOC%
 ---++ Introduction
 
@@ -17,9 +16,9 @@ Visit the [[http://www.graphviz.org/Gallery.php][Graphviz gallery]] to see some
 
 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 <a target="_top" href="http://foswiki.org/System/ForceNewRevision">http://foswiki.org/System/ForceNewRevision</a> and config parameter =$Foswiki::cfg{ReplaceIfEditedAgainWithin} = 0= ), then every updated attachment will result in a new topic revision. The alternative to this behavior is to use the expert parameter attachPath - set in bin/configure - to configure the plugin to do direct file I/O and bypass the attach API.
 
-Direct file I/O results in a considerable performance improvement.  Initial rendering of this topic on a test system resulted in a reduction of time to generate the attachments and initially display from 60 seconds down to approximately 8 seconds.
+Direct file I/O results in a considerable performance improvement. Initial rendering of this topic on a test system resulted in a reduction of time to generate the attachments and initially display from 60 seconds down to approximately 8 seconds.
 
-| %X% *Caution* The plugin will also update attached files during __Preview__. If the edit is subsequently canceled, the attachments will be regenerated again. |
+| %X% *Caution* The plugin will also update attached files during __Preview__. If the edit is subsequently cancelled, the attachments will be regenerated again. |
 
 The output of the &lt;dot&gt; command is cached as attachments to the topic. Any change to the &lt;dot&gt; input will result in the attachments being updated.
 
@@ -34,6 +33,15 @@ Default behavior is to leave any previously generated attachments even if the =&
 If a topic is renamed, the ==-filehash== file in the workarea directory will be renamed as well and regeneration of attachment files will be avoided.
 
 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.
+   * A client side image map can be generated and used for active links within =JPG= and =PNG= images. =SVG= graphics support links natively and do not require Image Maps, however a map can be generated for fallback images used by older browsers.
+   * =JPG= and =PNG= images can be created using antialiased text. See more details below. Antialiased text is not applicable to =SVG= graphics.
+   * =SVG= images are inserted inline using the &lt;object&gt; tag. 
+      * Antialias is disabled when =SVG= images are requested
+      * 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.
 ---+++ The !GraphViz Engine
 
 <nop>DirectedGraphPlugin supports the following engines:
@@ -56,7 +64,7 @@ You can use the following parameters in the =dot= tag to control the rendering o
 | =library="Main.GroupIcons"= | Which icon library topic to use for custom shapes ([shapefile] parameter). Needs to be explicitly set, also if icons are attached locally to the current graph topic. See demo below. | =System.DirectedGraphPlugin= |
 | =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.  | =graph_nn= nn increments per graph |
 | =hideattachments="on"= | Set whether or not attachments should be hidden from the attachment table | =on= |
-| =inlineattachment="png"= | Specifies the type of file to be attached inline to the page. Must be png or jpg. | =png= |
+| =inline="png"<br />inlineattach="png"= | Specifies the type of file to be attached inline to the page. Must be png or jpg or svg. | =png= |
 | =linkattachments="off"= | Add links for file types other than the inline type if present | =off= |
 | =dothash="on"= | Controls the hash calculation against the dot command input. If the dot hash is disabled, a previously created .png file will not be recreated unless the attachment is deleted, or the =dothash= parameter is enabled or removed. This can be used to create a portable topic and attachments that can be moved without regenerating all of the graphs. Used in the HowtoDirectedGraphs topic. | =on= |
 | =forceattachapi="off"= | Force standard Foswiki attachment API processing. Ignores setting of configure attachPath and attachUrlPath parameters. Used to create portable topic across Foswiki installations. | =off= |
@@ -171,16 +179,15 @@ digraph G {
 
 ---+++ Usecase description / state diagram
 
-View source of this page to see graph description.
-
+To view the =dot= input for this example, click the =[dot]= link located below the diagram.
 <sticky>
 <table><tr><td valign="top" width="25%">
 __You get: (simulated)__ %BR%
 <img src="%ATTACHURLPATH%/usecase_sample.png" alt="usecase_sample.png" width='534' height='1000' />
 </td>
 <td valign="top" width="25%">
 __You get: (if installed)__ %BR%
-<dot antialias="on" size="1000x1000">
+<dot antialias="on" size="1000x1000" vectorformats="dot">
 digraph G {
  size="7,7";
  graph [rankdir="TB" label="1st Time Use/Phone Registration" fontsize=12 bgcolor="#eeeeff"];
@@ -236,7 +243,7 @@ digraph G {
 
 This is a typical example of a component architecture drawing (This kind of graph is also easy to do in Foswiki:Extensions.JHotDrawPlugin if you like the look but you prefer to draw it manually using your mouse).
 
-View source of this page for graph description.
+Click the =[dot]= link located below the diagram to view the input. Note that this example is an inline =SVG= with fallback to =PNG=
 
 <sticky>
 <table><tr><td valign="top" width="25%">
@@ -245,7 +252,7 @@ __You get: (simulated)__ %BR%
 </td></tr>
 <tr><td valign="top" width="25%">
 __You get: (if installed)__ %BR%
-<dot antialias="on" size="918x251" map="on">
+<dot inline="svg" map="1" vectorformats="dot">
 digraph G {
   graph [rankdir=LR, size="9.5,2.5"]
   subgraph cluster_0 {
@@ -271,7 +278,7 @@ digraph G {
   subgraph cluster_1 {
     graph [label="Server 1"]
     httpd1 [label=httpd URL="http://httpd.apache.org/"]
-    webdot [label="/webdot" style=filled fillcolor=yellow color=black URL="/webdot/"]
+    webdot [label="/cgi-bin/webdot" style=filled fillcolor=yellow color=black URL="/webdot/"]
   }
   subgraph cluster_2 {
     graph [label="Server 2"]
@@ -291,16 +298,15 @@ digraph G {
 
 This type of graph can also easily be extended, for instance making network nodes clickable, pointing to asset databases or similar.
 
-View source of this page for graph description.
-
+Click the =[dot]= link below the diagram to view the input.
 <sticky>
 <table><tr><td valign="top" width="25%">
 __You get: (simulated)__ %BR%
 <img src="%ATTACHURLPATH%/sample_simple_lan_setup.png" alt="sample_simple_lan_setup.png" width='206' height='300' />
 </td>
 <td valign="top" width="25%">
 __You get: (if installed)__ %BR%
-<dot engine="dot"  size="300x300" library="System.DirectedGraphPlugin">
+<dot engine="dot"  size="300x300" library="System.DirectedGraphPlugin" vectorformats="dot">
 digraph G { size="2,3!"; dpi="100";
     edge [arrowhead=none color=blue];
     node [fontcolor=blue color=white];
@@ -355,6 +361,8 @@ digraph G { size="2,3!"; dpi="100";
    * #Set DIRECTEDGRAPHPLUGIN_DENSITY = 300
    * #Set DIRECTEDGRAPHPLUGIN_HIDEATTACHMENTS = on
    * #Set DIRECTEDGRAPHPLUGIN_INLINEATTACHMENT = png
+   * #Set DIRECTEDGRAPHPLUGIN_SVGFALLBACK= png
+   * #Set DIRECTEDGRAPHPLUGIN_SVGLINKTARGET = on
    * #Set DIRECTEDGRAPHPLUGIN_LINKATTACHMENTS = on
    * #Set DIRECTEDGRAPHPLUGIN_DELETEATTACHMENTS = off
    * #Set DIRECTEDGRAPHPLUGIN_FORCEATTACHAPI = off
@@ -371,8 +379,10 @@ Changes to the settings marked %X% will cause changes to the file hash. This wil
 | DIRECTEDGRAPHPLUGIN_ANTIALIAS | %X% Antialias option. If set to =on= the plugin will use the =convert= binary from the imagemagick package to pretty print graphs. This option should not be used with clientside maps as pixel dimensions are usually altered in this process and therefore the "hot spot" locations will not match the generated image. With antialiasing off, rendering size is controlled by =dot= (can be effected by an eventual size parameter in the digraph description), with antialiasing on you set the final image size in pixels explicitly with the size parameter. (If you must use an image map with this option, take care manually that the two generated pixel sizes match). | =off= |
 | DIRECTEDGRAPHPLUGIN_DENSITY | %X% Default density (dpi) for antialias option. 300 dpi should be sufficient for most purposes (if your graphs look blurred at large image sizes try using a higher value). | =300= |
 | DIRECTEDGRAPHPLUGIN_HIDEATTACHMENTS | %X% Set whether or not attached files should be automatically hidden in the attachments table. | =on= |
-| DIRECTEDGRAPHPLUGIN_INLINEATTACHMENT | %X% Set the format for inline attachment files. | =png= |
-| DIRECTEDGRAPHPLUGIN_LINKATTACHMENTS | <p>Include links for other attachment types if specified.</p> | =on= |
+| DIRECTEDGRAPHPLUGIN_INLINEATTACHMENT | %X% Set the format for inline attachment files. png, jpg or svg | =png= |
+| DIRECTEDGRAPHPLUGIN_SVGFALLBACK | Set a fallback image type for older browsers when SVG inline is set | =png= |
+| DIRECTEDGRAPHPLUGIN_SVGLINKTARGET | Modify the generated SVG with a =target="_top"= attribute. This makes link behaviour compatible between IE and Firefox | =on= |
+| DIRECTEDGRAPHPLUGIN_LINKATTACHMENT | Include links for other attachment types if specified. | =on= |
 | DIRECTEDGRAPHPLUGIN_DELETEATTACHMENTS | If enabled, the plugin will delete any remaining attachments when a =&lt;dot&gt;= is removed or modified. | =off= |
 | DIRECTEDGRAPHPLUGIN_FORCEATTACHAPI | If enabled, the plugin will ignore the "configure" settings of =attachPath= and =attachUrlPath=. Forcing use of the attachment API can be used to create topics that are portable across Foswiki installations. (for example, the HowtoDirectedGraphs topic) It can be also used to get standard attachment revision history handling on the generated attachments. [This parameter is ignored and the Foswiki attachment API always used if the configure settings =attachPath= and =attachUrlPath= are not supplied. | =off= |
 | DIRECTEDGRAPHPLUGIN_SIZE | %X% Default image size (pixels, =widthxheight=) for antialias option (keeps aspect ratio; enlarges until max of one of the dimensions is reached). | =800x600= |
@@ -444,6 +454,7 @@ There are two ways to accomplish antialiased output. The older method, enabled b
    * <nop>ImageMagick uses <nop>GhostScript internally to from postscript.
 This method is not compatible with client side image maps unless the imagesize rendered by graphviz is the same as the final output from ImageMagick. For example, the following parameters will result in compatible maps.
 
+Antialiasing is not compatible with inline =svg= graphics and will be ignored if =inline="svg"= is specified.
    $ dot parameters passed to =convert=: antialias="1" size="300x300" density="100" library="System.DirectedGraphPlugin" 
       * Size the image size in dots, density is dots per inch.
    $ graph parameters used by =dot=: digraph G { size="2,3!"; dpi="100"; 
@@ -476,9 +487,10 @@ Details on how to install cairo, graphviz and imagemagick are beyond the scope o
 |  Home: | http://foswiki.org/Extensions/%TOPIC%Dev |
 |  Support: | http://foswiki.org/Support/%TOPIC% |
 |  Change History: | <!-- versions below in reverse order --> |
+|  7 Sep 2009: | Foswikitask:Item8234, Foswikitask:Item8239, Foswikitask:Item8241 - Add support for inline SVG objects. Fix issues with recursive rendering, CGI acceleration |
 |  28 Jun 2009: | Foswikitask:Item1778 - Notify !WysiwygPlugin about &lt;dot&gt; markup so that it is protected in WYSIWYG editors --Foswiki:Main.MichaelTempest |
-|  5 Apr 2009: | Foswikitask:Item8102 - Improve defaults, configure settings now optional --Foswiki:Main.GeorgeClark |
-|  25 Mar 2009: | Foswikitask:Item1201, Foswikitask:Item1360 - Configure script fails on perl 5.10. %BR% Foswikitask:Item8086 - Direct File I/O fails. -- Foswiki:Main.GeorgeClark |
+|  5 Apr 2009: | Foswikitask:Item8102 - Improve defaults, configure settings now optional --Foswiki:Main.GeorgeClar |
+|  25 Mar 2009: | Foswikitask:Item1201, Foswikitask:Item1360 - Configure script fails on perl 5.10. %BR% Foswikitask:Item8086 - Direct File I/O failis. -- Foswiki:Main.GeorgeClark |
 |  8 Jan 2009: | Foswikitask:Item8035: Uninitialized variables reported in server Error log.-- Foswiki:Main.GeorgeClark |
 |  14 Dec 2008: | Foswikitask:Item8031: Port to Foswiki -- Foswiki:Main.GeorgeClark |
 |  11 Oct 2008: | TWikibug:Item6058: Incompatibilities with Windows, improved some error messages. --TWiki:Main.GeorgeClark |