1 <?php rcs_id('$Id: VisualWiki.php,v 1.4 2002-08-27 22:34:17 rurban Exp $');
3 Copyright (C) 2002 Johannes Große (Johannes Große)
5 This file is (not yet) part of PhpWiki.
7 PhpWiki is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
12 PhpWiki is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with PhpWiki; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 * Produces graphical site map of PhpWiki
23 * Example for an image map creating plugin. It produces a graphical
24 * sitemap of PhpWiki by calling the <code>dot</code> commandline tool
25 * from graphviz (http://www.graphviz.org).
26 * @author Johannes Große
29 define('VISUALWIKI_ALLOWOPTIONS',true);
30 // Name of the Truetypefont - Helvetica is probably easier to read
31 //define('VISUALWIKIFONT','Helvetica');
32 //define('VISUALWIKIFONT','Times');
33 define('VISUALWIKIFONT','Arial');
34 $dotbin = '/usr/local/bin/dot';
36 if (!defined('VISUALWIKI_ALLOWOPTIONS')) define('VISUALWIKI_ALLOWOPTIONS',false);
38 require_once "lib/WikiPluginCached.php";
40 class WikiPlugin_VisualWiki extends WikiPluginCached {
42 * Sets plugin type to map production
44 function getPluginType() {
45 return PLUGIN_CACHED_MAP;
49 * Sets the plugin's name to VisualWiki. It can be called by
50 * <code><?plugin VisualWiki?></code>, now. This
51 * name must correspond to the filename and the class name.
58 * Sets textual description.
60 function getDescription() {
61 return 'Visualizes the Wiki structure in a graph.';
65 * Returns default arguments. This is put into a separate
66 * function to allow its usage by both <code>getDefaultArguments</code>
67 * and <code>checkArguments</code>
69 function defaultarguments() {
70 return array('imgtype' => 'png',
73 'colorby' => 'age', // sort by 'age' or 'revtime'
81 'neighbour_list' => '',
89 * Sets the default arguments. WikiPlugin also regards these as
90 * the allowed arguments. Since WikiPluginCached stores an image
91 * for each different set of parameters, there can be a lot of
92 * these (large) graphs if you allow different parameters.
93 * Set <code>VISUALWIKI_ALLOWOPTIONS</code> to <code>false</code>
94 * to allow no options to be set and use only the default paramters.
95 * This will need an disk space of about 20 Kbyte all the time.
97 function getDefaultArguments() {
98 if (VISUALWIKI_ALLOWOPTIONS)
99 return $this->defaultarguments();
105 * Substitutes each forbidden parameter value by the default value
106 * defined in <code>defaultarguments</code>.
108 function checkArguments(&$arg) {
110 $def = $this->defaultarguments();
111 if (($width<3) ||($width>15)) $arg['width'] = $def['width'];
112 if (($height<3) ||($height>20)) $arg['height'] = $def['height'];
113 if (($fontsize<8) ||($fontsize>24)) $arg['fontsize'] = $def['fontsize'];
114 if (!in_array($label,array('name','number')))
115 $arg['label'] = $def['label'];
116 if (!in_array($shape,array('ellipse','box','point','circle','plaintext')))
117 $arg['shape'] = $def['shape'];
118 if (!in_array($colorby,array('age','revtime')))
119 $arg['colorby'] = $def['colorby'];
120 if (!in_array($fillnodes,array('on','off')))
121 $arg['fillnodes'] = $def['fillnodes'];
122 if (($large_nb<0) ||($large_nb>50)) $arg['large_nb'] = $def['large_nb'];
123 if (($recent_nb<0) ||($recent_nb>50)) $arg['recent_nb'] = $def['recent_nb'];
124 if (($refined_nb<0) ||($refined_nb>50)) $arg['refined_nb'] = $def['refined_nb'];
125 if (($backlink_nb<0)||($backlink_nb>50)) $arg['backlink_nb'] = $def['backlink_nb'];
126 // ToDo: check if "ImageCreateFrom$imgtype"() exists.
127 if (!in_array($imgtype,$GLOBALS['CacheParams']['imgtypes']))
128 $arg['imgtype'] = $def['imgtype'];
129 if (empty($fontname)) $arg['fontname'] = VISUALWIKIFONT;
133 * Checks options, creates help page if necessary, calls both
134 * database access and image map production functions.
135 * @return array($map,$html)
137 function getMap($dbi, $argarray, $request) {
138 if (!VISUALWIKI_ALLOWOPTIONS)
139 $argarray = $this->defaultarguments();
140 $this->checkArguments($argarray);
141 //extract($argarray);
142 if ($argarray['help'])
143 return array($this->helpImage(), ' '); // FIXME
144 $this->createColors();
145 $this->extract_wikipages($dbi, $argarray);
146 /* ($dbi, $large, $recent, $refined, $backlink,
147 $neighbour, $excludelist, $includelist,$color );*/
148 return $this->invokeDot($argarray);
149 /*($width,$height,$color,$shape,$text);*/
153 * Sets the expire time to one day (so the image producing
154 * functions are called seldomly) or to about two minutes
155 * if a help screen is created.
157 function getExpire($dbi, $argarray, $request) {
158 if ($argarray['help'])
159 return '+120'; // 2 minutes
160 return sprintf('+%d',3*86000); // approx 3 days
164 * Sets the imagetype according to user wishes and
165 * relies on WikiPluginCached to catch illegal image
167 * (I feel unsure whether this option is reasonable in
168 * this case, because png will definitely have the
171 * @return string 'png', 'gif', 'jpeg'
173 function getImageType($dbi, $argarray, $request) {
174 return $argarray['imgtype'];
178 * This gives an alternative text description of
179 * the image map. I do not know whether it interferes
180 * with the <code>title</code> attributes in <area>
181 * tags of the image map. Perhaps this will be removed.
184 function getAlt($dbi, $argstr, $request) {
185 return $this->getDescription();
188 // ------------------------------------------------------------------------------------------
191 * Returns an image containing a usage description of the plugin.
192 * @return string image handle
194 function helpImage() {
195 $def = $this->defaultarguments();
196 $other_imgtypes = $GLOBALS['CacheParams']['imgtypes'];
197 unset ($other_imgtypes[$def['imgtype']]);
199 '<?plugin '.$this->getName() .
200 ' img' => ' = "' . $def['imgtype'] . "(default)|" . join('|',$GLOBALS['CacheParams']['imgtypes']).'"',
201 'width' => ' = "width in inches"',
202 'height' => ' = "height in inches"',
203 'fontname' => ' = "font family"',
204 'fontsize' => ' = "fontsize in points"',
205 'colorby' => ' = "age|revtime|none"',
206 'fillnodes' => ' = "on|off"',
207 'shape' => ' = "ellipse(default)|box|circle|point"',
208 'label' => ' = "name|number"',
209 'large_nb' => ' = "number of largest pages to be selected"',
210 'recent_nb' => ' = "number of youngest pages"',
211 'refined_nb' => ' = "#pages with smallest time between revisions"',
212 'backlink_nb' => ' = "number of pages with most backlinks"',
213 'neighbour_list' => ' = "find pages linked from and to these pages"',
214 'exclude_list' => ' = "colon separated list of pages to be excluded"',
215 'include_list' => ' = "colon separated list" ?>'
218 foreach($helparr as $alignright => $alignleft) {
219 $length = max($length, strlen($alignright));
222 foreach($helparr as $alignright => $alignleft) {
223 $helptext .= substr(' '
224 . $alignright, -$length).$alignleft."\n";
226 return $this->text2img($helptext,4,array(1,0,0), array(255,255,255));
231 * Selects the first (smallest or biggest) WikiPages in
234 * @param number integer number of page names to be found
235 * @param category string attribute of the pages which is used
237 * @param minimum boolean true finds smallest, false finds biggest
238 * @return array list of page names found to be the best
240 function findbest($number, $category, $minimum ) {
241 // select the $number best in the category '$category'
242 $pages = &$this->pages;
243 $names = &$this->names;
247 foreach($names as $name) {
248 if ($i++>=$number) break;
249 $selected[$name] = $pages[$name][$category];
251 //echo "<pre>$category "; var_dump($selected); "</pre>";
252 $compareto = $minimum ? 0x79999999 : -0x79999999;
255 foreach ($names as $name) {
256 if ($i++<$number) continue;
258 if (($crit = $pages[$name][$category]) < $compareto) {
259 $selected[$name] = $crit;
260 asort($selected,SORT_NUMERIC);
261 array_pop($selected);
262 $compareto = end($selected);
264 } elseif (($crit = $pages[$name][$category]) > $compareto) {
265 $selected[$name] = $crit;
266 arsort($selected,SORT_NUMERIC);
267 array_pop($selected);
268 $compareto = end($selected);
271 //echo "<pre>$category "; var_dump($selected); "</pre>";
273 return array_keys($selected);
278 * Extracts a subset of all pages from the wiki and find their
279 * connections to other pages. Also collects some page features
280 * like size, age, revision number which are used to find the
281 * most attractive pages.
283 * @param dbi WikiDB database handle to access all Wiki pages
284 * @param LARGE integer number of largest pages which should
286 * @param RECENT integer number of the youngest pages to be included
287 * @param REFINED integer number of the pages with shortes revision interval
288 * @param BACKLINK integer number of the pages with most backlinks
289 * @param EXCLUDELIST string colon ':' separated list of page names which
290 * should not be displayed (like PhpWiki, for example)
291 * @param INCLUDELIST string colon separated list of pages which are allways
292 * included (for example your own page :)
293 * @param COLOR string 'age', 'revtime' or 'none'; Selects which page
294 * feature is used to determine the filling color of
295 * the nodes in the graph.
298 function extract_wikipages($dbi, $argarray) {
299 // $LARGE, $RECENT, $REFINED, $BACKLINK, $NEIGHBOUR, $EXCLUDELIST, $INCLUDELIST,$COLOR
303 // FIXME: gettextify?
304 $exclude_list = explode(':',$exclude_list);
305 $include_list = explode(':',$include_list);
306 $neighbour_list = explode(':',$neighbour_list);
308 // FIXME remove INCLUDED from EXCLUDED
311 $allpages = $dbi->getAllPages();
312 $pages = &$this->pages;
314 while ($page = $allpages->next()) {
315 $name = $page->getName();
317 // skip exluded pages
318 if (in_array($name,$exclude_list)) continue;
320 // false = get links from actual page
321 // true = get links to actual page ("backlinks")
322 $backlinks = $page->getLinks(true);
324 $bconnection = array();
325 while ($blink = $backlinks->next()) {
326 array_push($bconnection, $blink->getName());
330 // include all neighbours of pages listed in $NEIGHBOUR
331 if (in_array($name,$neighbour_list)) {
332 $l = $page->getLinks(false);
334 while ($link = $l->next()) {
335 array_push($con, $link->getName());
337 $include_list = array_merge($include_list,$bconnection,$con);
343 $currev = $page->getCurrentRevision();
345 $pages[$name] = array(
346 'age' => $now-$currev->get('mtime'),
347 'revnr' => $currev->getVersion(),
349 'backlink_nb' => count($bconnection),
350 'backlinks' => $bconnection,
351 'size' => 1000 // FIXME
353 $pages[$name]['revtime'] = $pages[$name]['age']/($pages[$name]['revnr']);
358 $this->names = array_keys($pages);
360 $countpages = count($pages);
362 // now select each page matching to given parameters
363 $all_selected = array_unique(array_merge(
364 $this->findbest($recent_nb, 'age', true),
365 $this->findbest($refined_nb, 'revtime', true),
366 $x=$this->findbest($backlink_nb, 'backlink_nb', false),
367 // $this->findbest($large_nb, 'size', false),
370 foreach($all_selected as $name)
371 if (isset($pages[$name]))
372 $newpages[$name] = $pages[$name];
375 $this->pages = $newpages;
376 $pages = &$this->pages;
377 $this->names = array_keys($pages);
379 unset($all_selected);
381 $countpages = count($pages);
383 // remove dead links and collect links
385 while( list($name,$page) = each($pages) ) {
386 if (is_array($page['backlinks'])) {
387 reset($page['backlinks']);
388 while ( list($index, $link) = each( $page['backlinks'] ) ) {
389 if ( !isset($pages[$link]) || $link == $name ) {
390 unset($pages[$name]['backlinks'][$index]);
392 array_push($pages[$link]['links'],$name);
393 //array_push($this->everylink, array($link,$name));
399 if ($colorby=='none') return;
400 list($oldestname) = $this->findbest(1, $colorby, false);
401 $this->oldest = $pages[$oldestname][$colorby];
402 foreach($this->names as $name)
403 $pages[$name]['color'] = $this->getColor($pages[$name][$colorby]/$this->oldest);
404 } // extract_wikipages
407 * Creates the text file description of the graph needed to invoke
410 * @param filename string name of the dot file to be created
411 * @param width float width of the output graph in inches
412 * @param height float height of the graph in inches
413 * @param colorby string color sceme beeing used ('age','revtime','none')
414 * @param shape string node shape; 'ellipse','box','circle','point'
415 * @param label string 'name': label by name, 'number': label by unique number
416 * @return boolean error status; true=ok; false=error
418 function createDotFile($filename,$argarray) {
420 if (!$fp=fopen($filename, 'w'))
423 $fillstring = ($fillnodes=='on')?'style=filled,':'';
426 $names = &$this->names;
427 $pages = &$this->pages;
429 $nametonumber = array_flip($names);
431 $dot = "digraph VisualWiki {\n" // }
432 . " size=\"$width,$height\";\n ";
436 $dot .= "edge [arrowhead=none];\nnode [shape=$shape,fontname=$fontname,width=0.15,height=0.15,fontsize=$fontsize];\n";
439 $dot .= "node [shape=$shape,fontname=$fontname,width=0.4,height=0.4,fontsize=$fontsize];\n";
442 $dot .= "node [shape=$shape,fontname=$fontname,width=0.25,height=0.25,fontsize=$fontsize];\n";
445 $dot .= "node [fontname=$fontname,shape=$shape,fontsize=$fontsize];\n" ;
449 foreach ($names as $name) {
451 $url = rawurlencode($name);
452 // patch to allow Page/SubPage
453 $url = preg_replace('/' . urlencode(SUBPAGE_SEPARATOR) . '/',SUBPAGE_SEPARATOR,$url);
454 $nodename = ($label!='name'?$nametonumber[$name]+1:$name);
456 $dot .= " \"$nodename\" [URL=\"$url\"";
457 if ($colorby != 'none') {
458 $col = $pages[$name]['color'];
459 $dot .= sprintf(',%scolor="#%02X%02X%02X"',$fillstring, $col[0],$col[1],$col[2]);
463 if (!empty($pages[$name]['links'])) {
466 foreach($pages[$name]['links'] as $linkname)
467 $linkarray[] = $nametonumber[$linkname]+1;
469 $linkarray = $pages[$name]['links'];
470 $linkstring = join('"; "', $linkarray );
472 $c = count($pages[$name]['links']);
473 $dot .= " \"$nodename\" -> "
480 if ($colorby!='none') {
481 $dot .= "\n subgraph cluster_legend {\n"
482 . " node[fontname=$fontname,shape=box,width=0.4,height=0.4,fontsize=$fontsize];\n"
483 . " fillcolor=lightgrey;\n"
485 . " fontname=$fontname;\n"
486 . " fontsize=$fontsize;\n"
487 . " label=\"".gettext("Legend")."\";\n";
488 $oldest= ceil($this->oldest/(24*3600));
491 for($i=0;$i<$max;$i++) {
492 $time = floor($i/$max*$oldest);
493 $name = '"'.$time.' '.gettext('days').'"';
494 $col = $this->getColor($i/$max);
495 $dot .= sprintf(' %s [%scolor="#%02X%02X%02X"];',
496 $name, $fillstring,$col[0],$col[1],$col[2]) . "\n";
499 $dot .= ' '. join(' -> ', $legend)
507 $ok = fwrite($fp, $dot);
508 $ok = fclose($fp) && $ok; // close anyway
514 * Execute system command.
516 * @param cmd string command to be invoked
517 * @return boolean error status; true=ok; false=error
519 function execute($cmd) {
520 exec($cmd, $errortxt, $returnval);
521 return ($returnval == 0);
525 * Produces a dot file, calls dot twice to obtain an image and a
526 * text description of active areas for hyperlinking and returns
527 * an image and an html map.
529 * @param width float width of the output graph in inches
530 * @param height float height of the graph in inches
531 * @param colorby string color sceme beeing used ('age','revtime','none')
532 * @param shape string node shape; 'ellipse','box','circle','point'
533 * @param label string not used anymore
535 function invokeDot($argarray) {
536 $cacheparams = $GLOBALS['CacheParams'];
537 $tempfiles = tempnam($cacheparams['cache_dir'],'VisualWiki');
538 $gif = $argarray['imgtype'];
539 $ImageCreateFromFunc = "ImageCreateFrom$gif";
541 && $this->createDotFile($tempfiles.'.dot',$argarray)
542 && $this->execute("$dotbin -T$gif $tempfiles.dot -o $tempfiles.$gif")
543 && $this->execute("$dotbin -Timap $tempfiles.dot -o $tempfiles.map")
544 && file_exists( "$tempfiles.$gif" )
545 && file_exists( $tempfiles.'.map' )
546 && ($img = $ImageCreateFromFunc( "$tempfiles.$gif" ))
547 && ($fp = fopen($tempfiles.'.map','r'));
552 $line = fgets($fp,1000);
553 if (substr($line,0,1)=='#') continue;
554 list($shape,$url,$e1,$e2,$e3,$e4) = sscanf($line,"%s %s %d,%d %d,%d");
556 if ($shape!='rect') continue;
558 // dot sometimes gives not allways the right order so
559 // so we have to sort a bit
564 $map->pushContent(HTML::area( array(
566 'coords' => "$x1,$y1,$x2,$y2",
568 'title' => rawurldecode($url),
574 // clean up tempfiles
575 if ($ok and empty($_GET['debug']) and $tempfiles) {
577 unlink("$tempfiles.$gif");
578 unlink($tempfiles.'.map');
579 unlink($tempfiles.'.dot');
583 return array($img,$map);
585 return array(false,false);
589 * Prepares some rainbow colors for the nodes of the graph
590 * and stores them in an array which may be accessed with
591 * <code>getColor</code>.
593 function createColors() {
594 $predefcolors = array(
595 array('red' => 255, 'green' => 0, 'blue' => 0),
596 array('red' => 255, 'green' => 255, 'blue' => 0),
597 array('red' => 0, 'green' => 255, 'blue' => 0),
598 array('red' => 0, 'green' => 255, 'blue' => 255),
599 array('red' => 0, 'green' => 0, 'blue' => 255),
600 array('red' => 100, 'green' => 100, 'blue' => 100)
604 $numberofcolors = count($predefcolors)*$steps;
607 foreach($predefcolors as $color) {
608 if ($promille < 0) { $oldcolor = $color; $promille=0; continue; }
609 for ($i=0; $i<$steps; $i++)
610 $this->ColorTab[++$promille / $numberofcolors * 1000] = array(
611 floor(interpolate( $oldcolor['red'], $color['red'], $i/$steps )),
612 floor(interpolate( $oldcolor['green'], $color['green'], $i/$steps )),
613 floor(interpolate( $oldcolor['blue'], $color['blue'], $i/$steps ))
617 //echo"<pre>"; var_dump($this->ColorTab); echo "</pre>";
621 * Translates a value from 0.0 to 1.0 into rainbow color.
622 * red -> orange -> green -> blue -> gray
624 * @param promille float value between 0.0 and 1.0
625 * @return array(red,green,blue)
627 function getColor($promille) {
628 foreach( $this->ColorTab as $pro => $col ) {
629 if ($promille*1000 < $pro)
632 $lastcol = end($this->ColorTab);
635 } // WikiPlugin_VisualWiki
638 * Linear interpolates a value between two point a and b
640 * @return float interpolated value
643 function interpolate($a, $b, $pos) {
644 return $a + ($b-$a)*$pos;