2 rcs_id('$Id: VisualWiki.php,v 1.6 2003-01-18 22:11:45 carstenklapp Exp $');
4 Copyright (C) 2002 Johannes Große (Johannes Große)
6 This file is (not yet) part of PhpWiki.
8 PhpWiki is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2 of the License, or
11 (at your option) any later version.
13 PhpWiki is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with PhpWiki; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 * Produces graphical site map of PhpWiki
25 * Example for an image map creating plugin. It produces a graphical
26 * sitemap of PhpWiki by calling the <code>dot</code> commandline tool
27 * from graphviz (http://www.graphviz.org).
28 * @author Johannes Große
31 define('VISUALWIKI_ALLOWOPTIONS', true);
32 // Name of the Truetypefont - Helvetica is probably easier to read
33 //define('VISUALWIKIFONT', 'Helvetica');
34 //define('VISUALWIKIFONT', 'Times');
35 define('VISUALWIKIFONT', 'Arial');
36 $dotbin = '/usr/local/bin/dot';
38 if (!defined('VISUALWIKI_ALLOWOPTIONS'))
39 define('VISUALWIKI_ALLOWOPTIONS', false);
41 require_once "lib/WikiPluginCached.php";
43 class WikiPlugin_VisualWiki
44 extends WikiPluginCached
47 * Sets plugin type to map production
49 function getPluginType() {
50 return PLUGIN_CACHED_MAP;
54 * Sets the plugin's name to VisualWiki. It can be called by
55 * <code><?plugin VisualWiki?></code>, now. This
56 * name must correspond to the filename and the class name.
62 function getVersion() {
63 return preg_replace("/[Revision: $]/", '',
68 * Sets textual description.
70 function getDescription() {
71 return _("Visualizes the Wiki structure in a graph using the 'dot' commandline tool from graphviz.");
75 * Returns default arguments. This is put into a separate
76 * function to allow its usage by both <code>getDefaultArguments</code>
77 * and <code>checkArguments</code>
79 function defaultarguments() {
80 return array('imgtype' => 'png',
83 'colorby' => 'age', // sort by 'age' or 'revtime'
91 'neighbour_list' => '',
99 * Sets the default arguments. WikiPlugin also regards these as
100 * the allowed arguments. Since WikiPluginCached stores an image
101 * for each different set of parameters, there can be a lot of
102 * these (large) graphs if you allow different parameters.
103 * Set <code>VISUALWIKI_ALLOWOPTIONS</code> to <code>false</code>
104 * to allow no options to be set and use only the default paramters.
105 * This will need an disk space of about 20 Kbyte all the time.
107 function getDefaultArguments() {
108 if (VISUALWIKI_ALLOWOPTIONS)
109 return $this->defaultarguments();
115 * Substitutes each forbidden parameter value by the default value
116 * defined in <code>defaultarguments</code>.
118 function checkArguments(&$arg) {
120 $def = $this->defaultarguments();
122 if (($width < 3) || ($width > 15))
123 $arg['width'] = $def['width'];
125 if (($height < 3) || ($height > 20))
126 $arg['height'] = $def['height'];
128 if (($fontsize < 8) || ($fontsize > 24))
129 $arg['fontsize'] = $def['fontsize'];
131 if (!in_array($label, array('name', 'number')))
132 $arg['label'] = $def['label'];
134 if (!in_array($shape, array('ellipse', 'box', 'point', 'circle',
136 $arg['shape'] = $def['shape'];
138 if (!in_array($colorby, array('age', 'revtime')))
139 $arg['colorby'] = $def['colorby'];
141 if (!in_array($fillnodes, array('on', 'off')))
142 $arg['fillnodes'] = $def['fillnodes'];
144 if (($large_nb < 0) || ($large_nb > 50))
145 $arg['large_nb'] = $def['large_nb'];
147 if (($recent_nb < 0) || ($recent_nb > 50))
148 $arg['recent_nb'] = $def['recent_nb'];
150 if (($refined_nb < 0 ) || ( $refined_nb > 50))
151 $arg['refined_nb'] = $def['refined_nb'];
153 if (($backlink_nb < 0) || ($backlink_nb > 50))
154 $arg['backlink_nb'] = $def['backlink_nb'];
156 // ToDo: check if "ImageCreateFrom$imgtype"() exists.
157 if (!in_array($imgtype, $GLOBALS['CacheParams']['imgtypes']))
158 $arg['imgtype'] = $def['imgtype'];
159 if (empty($fontname))
160 $arg['fontname'] = VISUALWIKIFONT;
164 * Checks options, creates help page if necessary, calls both
165 * database access and image map production functions.
166 * @return array($map,$html)
168 function getMap($dbi, $argarray, $request) {
169 if (!VISUALWIKI_ALLOWOPTIONS)
170 $argarray = $this->defaultarguments();
171 $this->checkArguments($argarray);
172 //extract($argarray);
173 if ($argarray['help'])
174 return array($this->helpImage(), ' '); // FIXME
175 $this->createColors();
176 $this->extract_wikipages($dbi, $argarray);
177 /* ($dbi, $large, $recent, $refined, $backlink,
178 $neighbour, $excludelist, $includelist, $color); */
179 return $this->invokeDot($argarray);
180 /* ($width, $height, $color, $shape, $text); */
184 * Sets the expire time to one day (so the image producing
185 * functions are called seldomly) or to about two minutes
186 * if a help screen is created.
188 function getExpire($dbi, $argarray, $request) {
189 if ($argarray['help'])
190 return '+120'; // 2 minutes
191 return sprintf('+%d', 3*86000); // approx 3 days
195 * Sets the imagetype according to user wishes and
196 * relies on WikiPluginCached to catch illegal image
198 * (I feel unsure whether this option is reasonable in
199 * this case, because png will definitely have the
202 * @return string 'png', 'gif', 'jpeg'
204 function getImageType($dbi, $argarray, $request) {
205 return $argarray['imgtype'];
209 * This gives an alternative text description of
210 * the image map. I do not know whether it interferes
211 * with the <code>title</code> attributes in <area>
212 * tags of the image map. Perhaps this will be removed.
215 function getAlt($dbi, $argstr, $request) {
216 return $this->getDescription();
219 // ------------------------------------------------------------------------------------------
222 * Returns an image containing a usage description of the plugin.
223 * @return string image handle
225 function helpImage() {
226 $def = $this->defaultarguments();
227 $other_imgtypes = $GLOBALS['CacheParams']['imgtypes'];
228 unset ($other_imgtypes[$def['imgtype']]);
230 '<?plugin '.$this->getName() .
231 ' img' => ' = "' . $def['imgtype'] . "(default)|" . join('|',$GLOBALS['CacheParams']['imgtypes']).'"',
232 'width' => ' = "width in inches"',
233 'height' => ' = "height in inches"',
234 'fontname' => ' = "font family"',
235 'fontsize' => ' = "fontsize in points"',
236 'colorby' => ' = "age|revtime|none"',
237 'fillnodes' => ' = "on|off"',
238 'shape' => ' = "ellipse(default)|box|circle|point"',
239 'label' => ' = "name|number"',
240 'large_nb' => ' = "number of largest pages to be selected"',
241 'recent_nb' => ' = "number of youngest pages"',
242 'refined_nb' => ' = "#pages with smallest time between revisions"',
243 'backlink_nb' => ' = "number of pages with most backlinks"',
244 'neighbour_list' => ' = "find pages linked from and to these pages"',
245 'exclude_list' => ' = "colon separated list of pages to be excluded"',
246 'include_list' => ' = "colon separated list" ?>'
249 foreach($helparr as $alignright => $alignleft) {
250 $length = max($length, strlen($alignright));
253 foreach($helparr as $alignright => $alignleft) {
254 $helptext .= substr(' '
255 . $alignright, -$length).$alignleft."\n";
257 return $this->text2img($helptext, 4, array(1, 0, 0),
258 array(255, 255, 255));
263 * Selects the first (smallest or biggest) WikiPages in
266 * @param number integer number of page names to be found
267 * @param category string attribute of the pages which is used
269 * @param minimum boolean true finds smallest, false finds biggest
270 * @return array list of page names found to be the best
272 function findbest($number, $category, $minimum ) {
273 // select the $number best in the category '$category'
274 $pages = &$this->pages;
275 $names = &$this->names;
279 foreach($names as $name) {
282 $selected[$name] = $pages[$name][$category];
284 //echo "<pre>$category "; var_dump($selected); "</pre>";
285 $compareto = $minimum ? 0x79999999 : -0x79999999;
288 foreach ($names as $name) {
292 if (($crit = $pages[$name][$category]) < $compareto) {
293 $selected[$name] = $crit;
294 asort($selected, SORT_NUMERIC);
295 array_pop($selected);
296 $compareto = end($selected);
298 } elseif (($crit = $pages[$name][$category]) > $compareto) {
299 $selected[$name] = $crit;
300 arsort($selected, SORT_NUMERIC);
301 array_pop($selected);
302 $compareto = end($selected);
305 //echo "<pre>$category "; var_dump($selected); "</pre>";
307 return array_keys($selected);
312 * Extracts a subset of all pages from the wiki and find their
313 * connections to other pages. Also collects some page features
314 * like size, age, revision number which are used to find the
315 * most attractive pages.
317 * @param dbi WikiDB database handle to access all Wiki pages
318 * @param LARGE integer number of largest pages which should
320 * @param RECENT integer number of the youngest pages to be included
321 * @param REFINED integer number of the pages with shortes revision
323 * @param BACKLINK integer number of the pages with most backlinks
324 * @param EXCLUDELIST string colon ':' separated list of page names which
325 * should not be displayed (like PhpWiki, for
327 * @param INCLUDELIST string colon separated list of pages which are
328 * allways included (for example your own
330 * @param COLOR string 'age', 'revtime' or 'none'; Selects which
331 * page feature is used to determine the
332 * filling color of the nodes in the graph.
335 function extract_wikipages($dbi, $argarray) {
336 // $LARGE, $RECENT, $REFINED, $BACKLINK, $NEIGHBOUR,
337 // $EXCLUDELIST, $INCLUDELIST,$COLOR
341 // FIXME: gettextify?
342 $exclude_list = explode(':', $exclude_list);
343 $include_list = explode(':', $include_list);
344 $neighbour_list = explode(':', $neighbour_list);
346 // FIXME remove INCLUDED from EXCLUDED
349 $allpages = $dbi->getAllPages();
350 $pages = &$this->pages;
352 while ($page = $allpages->next()) {
353 $name = $page->getName();
355 // skip exluded pages
356 if (in_array($name, $exclude_list)) continue;
358 // false = get links from actual page
359 // true = get links to actual page ("backlinks")
360 $backlinks = $page->getLinks(true);
362 $bconnection = array();
363 while ($blink = $backlinks->next()) {
364 array_push($bconnection, $blink->getName());
368 // include all neighbours of pages listed in $NEIGHBOUR
369 if (in_array($name,$neighbour_list)) {
370 $l = $page->getLinks(false);
372 while ($link = $l->next()) {
373 array_push($con, $link->getName());
375 $include_list = array_merge($include_list, $bconnection, $con);
381 $currev = $page->getCurrentRevision();
383 $pages[$name] = array(
384 'age' => $now-$currev->get('mtime'),
385 'revnr' => $currev->getVersion(),
387 'backlink_nb' => count($bconnection),
388 'backlinks' => $bconnection,
389 'size' => 1000 // FIXME
391 $pages[$name]['revtime'] = $pages[$name]['age'] / ($pages[$name]['revnr']);
396 $this->names = array_keys($pages);
398 $countpages = count($pages);
400 // now select each page matching to given parameters
401 $all_selected = array_unique(array_merge(
402 $this->findbest($recent_nb, 'age', true),
403 $this->findbest($refined_nb, 'revtime', true),
404 $x = $this->findbest($backlink_nb, 'backlink_nb', false),
405 // $this->findbest($large_nb, 'size', false),
408 foreach($all_selected as $name)
409 if (isset($pages[$name]))
410 $newpages[$name] = $pages[$name];
413 $this->pages = $newpages;
414 $pages = &$this->pages;
415 $this->names = array_keys($pages);
417 unset($all_selected);
419 $countpages = count($pages);
421 // remove dead links and collect links
423 while( list($name,$page) = each($pages) ) {
424 if (is_array($page['backlinks'])) {
425 reset($page['backlinks']);
426 while ( list($index, $link) = each( $page['backlinks'] ) ) {
427 if ( !isset($pages[$link]) || $link == $name ) {
428 unset($pages[$name]['backlinks'][$index]);
430 array_push($pages[$link]['links'],$name);
431 //array_push($this->everylink, array($link,$name));
437 if ($colorby == 'none')
439 list($oldestname) = $this->findbest(1, $colorby, false);
440 $this->oldest = $pages[$oldestname][$colorby];
441 foreach($this->names as $name)
442 $pages[$name]['color'] = $this->getColor($pages[$name][$colorby] / $this->oldest);
443 } // extract_wikipages
446 * Creates the text file description of the graph needed to invoke
449 * @param filename string name of the dot file to be created
450 * @param width float width of the output graph in inches
451 * @param height float height of the graph in inches
452 * @param colorby string color sceme beeing used ('age', 'revtime',
454 * @param shape string node shape; 'ellipse', 'box', 'circle', 'point'
455 * @param label string 'name': label by name,
456 * 'number': label by unique number
457 * @return boolean error status; true=ok; false=error
459 function createDotFile($filename, $argarray) {
461 if (!$fp = fopen($filename, 'w'))
464 $fillstring = ($fillnodes == 'on') ? 'style=filled,' : '';
467 $names = &$this->names;
468 $pages = &$this->pages;
470 $nametonumber = array_flip($names);
472 $dot = "digraph VisualWiki {\n" // }
473 . " size=\"$width,$height\";\n ";
477 $dot .= "edge [arrowhead=none];\nnode [shape=$shape,fontname=$fontname,width=0.15,height=0.15,fontsize=$fontsize];\n";
480 $dot .= "node [shape=$shape,fontname=$fontname,width=0.4,height=0.4,fontsize=$fontsize];\n";
483 $dot .= "node [shape=$shape,fontname=$fontname,width=0.25,height=0.25,fontsize=$fontsize];\n";
486 $dot .= "node [fontname=$fontname,shape=$shape,fontsize=$fontsize];\n" ;
490 foreach ($names as $name) {
492 $url = rawurlencode($name);
493 // patch to allow Page/SubPage
494 $url = preg_replace('/' . urlencode(SUBPAGE_SEPARATOR) . '/',
495 SUBPAGE_SEPARATOR, $url);
496 $nodename = ($label != 'name' ? $nametonumber[$name] + 1 : $name);
498 $dot .= " \"$nodename\" [URL=\"$url\"";
499 if ($colorby != 'none') {
500 $col = $pages[$name]['color'];
501 $dot .= sprintf(',%scolor="#%02X%02X%02X"', $fillstring,
502 $col[0], $col[1], $col[2]);
506 if (!empty($pages[$name]['links'])) {
508 if ($label != 'name')
509 foreach($pages[$name]['links'] as $linkname)
510 $linkarray[] = $nametonumber[$linkname] + 1;
512 $linkarray = $pages[$name]['links'];
513 $linkstring = join('"; "', $linkarray );
515 $c = count($pages[$name]['links']);
516 $dot .= " \"$nodename\" -> "
523 if ($colorby != 'none') {
524 $dot .= "\n subgraph cluster_legend {\n"
525 . " node[fontname=$fontname,shape=box,width=0.4,height=0.4,fontsize=$fontsize];\n"
526 . " fillcolor=lightgrey;\n"
528 . " fontname=$fontname;\n"
529 . " fontsize=$fontsize;\n"
530 . " label=\"".gettext("Legend")."\";\n";
531 $oldest= ceil($this->oldest / (24 * 3600));
534 for($i = 0; $i < $max; $i++) {
535 $time = floor($i / $max * $oldest);
536 $name = '"' . $time .' '. _("days") .'"';
537 $col = $this->getColor($i/$max);
538 $dot .= sprintf(' %s [%scolor="#%02X%02X%02X"];',
539 $name, $fillstring, $col[0], $col[1], $col[2])
543 $dot .= ' '. join(' -> ', $legend)
551 $ok = fwrite($fp, $dot);
552 $ok = fclose($fp) && $ok; // close anyway
558 * Execute system command.
560 * @param cmd string command to be invoked
561 * @return boolean error status; true=ok; false=error
563 function execute($cmd) {
564 exec($cmd, $errortxt, $returnval);
565 return ($returnval == 0);
569 * Produces a dot file, calls dot twice to obtain an image and a
570 * text description of active areas for hyperlinking and returns
571 * an image and an html map.
573 * @param width float width of the output graph in inches
574 * @param height float height of the graph in inches
575 * @param colorby string color sceme beeing used ('age', 'revtime',
577 * @param shape string node shape; 'ellipse', 'box', 'circle', 'point'
578 * @param label string not used anymore
580 function invokeDot($argarray) {
582 $cacheparams = $GLOBALS['CacheParams'];
583 $tempfiles = tempnam($cacheparams['cache_dir'], 'VisualWiki');
584 $gif = $argarray['imgtype'];
585 $ImageCreateFromFunc = "ImageCreateFrom$gif";
587 && $this->createDotFile($tempfiles.'.dot',$argarray)
588 && $this->execute("$dotbin -T$gif $tempfiles.dot -o $tempfiles.$gif")
589 && $this->execute("$dotbin -Timap $tempfiles.dot -o $tempfiles.map")
590 && file_exists( "$tempfiles.$gif" )
591 && file_exists( $tempfiles.'.map' )
592 && ($img = $ImageCreateFromFunc( "$tempfiles.$gif" ))
593 && ($fp = fopen($tempfiles.'.map','r'));
598 $line = fgets($fp, 1000);
599 if (substr($line, 0, 1) == '#')
601 list($shape, $url, $e1, $e2, $e3, $e4) = sscanf($line,
602 "%s %s %d,%d %d,%d");
603 if ($shape != 'rect')
606 // dot sometimes gives not allways the right order so
607 // so we have to sort a bit
612 $map->pushContent(HTML::area(array(
614 'coords' => "$x1,$y1,$x2,$y2",
616 'title' => rawurldecode($url),
622 // clean up tempfiles
623 if ($ok && empty($_GET['debug']) && $tempfiles) {
625 unlink("$tempfiles.$gif");
626 unlink($tempfiles . '.map');
627 unlink($tempfiles . '.dot');
631 return array($img, $map);
633 return array(false, false);
637 * Prepares some rainbow colors for the nodes of the graph
638 * and stores them in an array which may be accessed with
639 * <code>getColor</code>.
641 function createColors() {
642 $predefcolors = array(
643 array('red' => 255, 'green' => 0, 'blue' => 0),
644 array('red' => 255, 'green' => 255, 'blue' => 0),
645 array('red' => 0, 'green' => 255, 'blue' => 0),
646 array('red' => 0, 'green' => 255, 'blue' => 255),
647 array('red' => 0, 'green' => 0, 'blue' => 255),
648 array('red' => 100, 'green' => 100, 'blue' => 100)
652 $numberofcolors = count($predefcolors) * $steps;
655 foreach($predefcolors as $color) {
661 for ($i = 0; $i < $steps; $i++)
662 $this->ColorTab[++$promille / $numberofcolors * 1000] = array(
663 floor(interpolate( $oldcolor['red'], $color['red'], $i/$steps )),
664 floor(interpolate( $oldcolor['green'], $color['green'], $i/$steps )),
665 floor(interpolate( $oldcolor['blue'], $color['blue'], $i/$steps ))
669 //echo"<pre>"; var_dump($this->ColorTab); echo "</pre>";
673 * Translates a value from 0.0 to 1.0 into rainbow color.
674 * red -> orange -> green -> blue -> gray
676 * @param promille float value between 0.0 and 1.0
677 * @return array(red,green,blue)
679 function getColor($promille) {
680 foreach( $this->ColorTab as $pro => $col ) {
681 if ($promille*1000 < $pro)
684 $lastcol = end($this->ColorTab);
687 } // WikiPlugin_VisualWiki
690 * Linear interpolates a value between two point a and b
692 * @return float interpolated value
695 function interpolate($a, $b, $pos) {
696 return $a + ($b - $a) * $pos;
699 // $Log: not supported by cvs2svn $
705 // c-hanging-comment-ender-p: nil
706 // indent-tabs-mode: nil