TreePlugin < TWiki

---+!! Tree Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/TreePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/TreePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%.
Useful for dynamic site maps and threads.

---++ Syntax Rules

=%<nop>TREEVIEW{}%= displays topic children in a hierarchical tree <br /> =%<nop>TREE{}%= synonym of =%<nop>TREEVIEW{}%=

| *Parameter* | *Description* | *Default* |
| =web= | The web to search. | current web |
| =topic= | Specify tree's root topic. If none the entire web topics' tree is generated | none |
| =formatting= | Specify the formatting method <br /> =ullist= is a &lt;ul&gt;-list, see [[Plugins.TreePluginSamples#UlList][sample UL lists]] <br /> =ollist= is a &lt;ol&gt;-list, see [[Plugins.TreePluginSamples#OlList][sample OL lists]] <br /> =outline= is an outline list, see [[Plugins.TreePluginSamples#SampleOutlines][sample Outlines]] <br /> =hlist= is a &lt;h _n_ &gt;-list of section heads, see [[Plugins.TreePluginSamples#SampleHList][sample Headlines]] <br /> =coloroutline:colorlist= is an outline formatting with level values turned into colors, see [[Plugins.TreePluginSamples#SampleNestedTables][sample Nested tables]]. Example: =formatting="coloroutline:#ffeeff,#eeffee,#ffffee,#eeeeff,#ffeeee,#eeffff"= <br /> =imageoutline:mode= is a way to incorporate images into the outline format, specifically to display thread-like and folder views, see [[Plugins.TreePluginSamples#SampleImageTrees][sample Image Trees]]. The general format is: imageoutline: _mode_ : _images_ : _imageformat_. Example: =formatting="imageoutline:thread"= or =formatting="imageoutline:thread:I.gif,white.gif,T.gif,L.gif:&lt;img src=\"$image\" border=\"0\"&gt;"=. | =outline= |
| =excludetopic= | Same meaning as TWiki.VarSEARCH =excludetopic=. Topics with excluded parent or processed like topic without parent. | none |
| =includetopic= | Same meaning as TWiki.VarSEARCH =topic=. Can improve processing time. | none |
| =startlevel= | The depth of the tree to start showing nodes from. To hide the root node, supply =startlevel="1"= (root is level 0). The displayed node depths are relative to the root topic. | =0= or =1= if =topic= is not specified |
| =stoplevel= | The depth of the tree to show, relative to start level. | =999= |
| =header= | Output the value within a =&lt;div&gt;= of class =treePluginHeader=. Suppressed if the tree is empty. | none |
| =footer= | Output the value within a =&lt;div&gt;= of class =treePluginFooter=. Suppressed if the tree is empty. | none |
| =zero= | Output the value within a =&lt;div&gt;= of class =treePluginZero= if the tree is empty. | none |
| =bookview= | List topics in BookView form. %RED%Not supported from v0.9. Instead use something like: %ENDCOLOR% <verbatim>%TREE{topic="GrandParent" formatting="outline" format="$outnum $topic <br /> $summary <hr />"}%</verbatim> | none |
| =format= | Specify the format for each node ( =outline= & =coloroutline=). The following pseudo-variable are supported on top of the ones described in TWiki.FormattedSearch: <br /> =$spacetopic= - the topic with spaces <br /> =$level= - the tree depth of the topic (in whatever format) <br /> =$count= - the topic's child position <br /> =$index= - the index of the topic in the tree. Starts from one. Most useful when used in combination with [[TWiki:Plugins.TreeBrowserPlugin][TreeBrowserPlugin]] <br /> =$outnum= - outline number for the topic (eg, 1.3.4.2) <br /> =$url= - the current topic's URL <br /> =$author= - the topic's last author %RED%Not supported from v0.9. Use =%<nop>AUTHOR%= instead. %ENDCOLOR% <br /> =$modTime= - the topic's modification time. %RED%Not supported from v0.9. Use =$date= instead. %ENDCOLOR% | none |
| =formatbranch= | - specify the format for a group of children ( =outline= & =coloroutline=) <br /> =$parent= - the text of a node <br /> =$children= - the text of all the node's children (if any) | none |
| =levelprefix= | Specify a prefix to a node format. The prefix is inserted =$level= times at the beginning of the rendered node format. It allows generation of trees using TWiki bullet list syntax thus enabling usage of !TreePlugin [[#Combination_with_TreeBrowserPlug][in combination with TreeBrowserPlugin]]. | none |
| =nodiv= | Suppress the =&lt;div&gt;= around the tree. Set to =2= to suppress =div= around =header=, =footer= and =zero=. Allows for trees concatenation. | none |
| =search= | Search string - use as a filter to narrow down the selection. (Not commonly used) | all topics |
| =scope= | Search scope: (Not commonly used) <br /> =scope="text"= - topic text (body) <br /> =scope="topic"= - topic name (title) <br /> =scope="all"= - title and body | ="text"= |
| =type= | Type of search. (Not commonly used) <br /> =type="keyword"= - Google like search syntax with plus, minus and quotes <br /> =type="word"= similar to type keyword but looking for whole words - <br /> =type="literal"= - exactly as specified <br /> =type="regex"= - a RegularExpression search <br /> =type="query"= - [[query search]] of form fields and other meta-data <br /> Details: See =type= parameter in [[%SYSTEMWEB%.VarSEARCH][SEARCH]] | ="literal"= |
| =separator= | Character string used to separate items in the tree | =\n= |
| =nocache= | Set to 1 to disable caching mechanism for that specific tree. Really a developer setting. (Not commonly used) | 0 |

---++ Samples

See the following page for sample usage and output:
   * [[Sandbox.TreePluginSamples]]

---+++ Usage

=%<nop>TREE{web="Sandbox" formatting="ullist"}%=

=%<nop>TREE{web="Sandbox"}%=

<verbatim>
%TREE{excludetopic="Web*" formatting="outline" format="* [[$topic][$spacetopic]]" levelprefix="   " startlevel="1"}%
</verbatim>

---+++ Combination with [[TWiki:Plugins.TreeBrowserPlugin][TreeBrowserPlugin]]

=%<nop>TREEBROWSER{"file" title="%<nop>WEB%"}%= %BR% =%<nop>TREEVIEW{web="%<nop>WEB%" topic="GrandParent" formatting="outline" format="* $topic" levelprefix=" "}%=

---++ Performance consideration

For each =%<nop>TREE%= or =%<nop>TREEVIEW%= tag a TWiki.VarSEARCH at topic scope is performed. To reduce the scope of that search one can use =includetopic= and =excludetopic=. Those two parameters should be used by TreePlugin users worried about performance. In fact they can potently greatly reduce the processing time.

For instance if you know that every topic in your tree has a common prefix you can easily make use of =includetopic=. Also when generating web tree you may want to =excludetopic= prefixed with _Web_.

---++ Plugin Settings

<!--
   * Set SHORTDESCRIPTION = Dynamically generate TWiki topic trees based on the parent-child relationship of topics
-->

Specify plug-in settings in =LocalSite.cfg=:
   * Set ={Plugins}{TreePlugin}{Debug}= to =1= to enable debug output. Set to =2= to get a lot more debug output.
   * Set ={Plugins}{TreePlugin}{NoCache}= to =1= to disable caching mechanism. Intended for development purposes only.

---++ Installation Instructions

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server. 
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section. 
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps: 
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==NotifyAuthorsPlugin.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/TreePlugin.txt== | Plugin topic |
        | ==data/Sandbox/HeadingOutlineSample.txt== | Outline example |
        | ==data/Sandbox/TreePluginSamples.txt== | Tree examples |
        | ==pub/TWiki/TreePlugin/*gif== | Image files |
        | ==lib/TWiki/Plugins/TreePlugin.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/TreePlugin/*.pm== | Plugin core modules |
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__: 
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Visit [[Sandbox.TreePluginSamples]] to see if the installation was successful
%ENDTWISTY%

---++ Plugin Info

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Authors: | TWiki:Main.SlavaKozlov (alpha release), TWiki:Main.StephaneLenclud (2006-2008)  |
|  Copyright: | &copy; 2002-2004 2002 Slava Kozlov, %BR% &copy; 2002-2015 TWiki:TWiki/TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2015-08-12 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2015-08-12: | TWikibug:Item7680: Fix missing newline in children bullets -- TWiki:Main.PeterThoeny |
|  2015-03-18: | TWikibug:Item7626: Fix TREEVIEW producing empty lines with out of bound bullets -- TWiki:Main.PeterThoeny |
|  2014-10-10: | TWikibug:Item7576: Support additional SEARCH parameters: search, scope, type -- TWiki:Main.PeterThoeny |
|  2010-08-21: | TWikibug:Item6562: Fix error Global symbol $RELEASE requires explicit package name |
|  2010-07-25: | TWikibug:Item6530: Doc fixes, changing TWIKIWEB to SYSTEMWEB |
|  28 Aug 2008 | 1.7 - Fixing warnings in apache logs. Fixing broken cache generation when using =excludetopic= or =includetopic=. Better support for Sub Webs and Non-Wiki words from TWiki:Main.ColasNahaboo. By TWiki:Main.StephaneLenclud |
|  10 Apr 2008 | 1.6 - File cache implementation. Massive performance improvement for Topic tree. No performance gain for Web tree. Added =nocache= parameter. Now using =LocalLib.cfg= for settings. By TWiki:Main.StephaneLenclud |
|  10 Apr 2008 | 1.5 - Slight performance improvement. Improved =header= parameter. Added =footer= and =zero= parameter. By TWiki:Main.StephaneLenclud |
|  29 Mar 2008 | 1.4 - Fixed endless loop in =imageoutline:thread=. Added =separator= parameter. By TWiki:Main.StephaneLenclud |
|  11 Jul 2007 | 1.3 - Fixed =$onum= to =$outnum= in documentation. Fixed endless loop on inconsistent/looping parent/child relationship. Not supporting =bookview= any more. Fixed =imageoutline:thread= not rendering. By TWiki:Main.StephaneLenclud |
|  7 Apr 2007 | 1.2 - Documentation improvement. Adding =includetopic= parameter. By TWiki:Main.StephaneLenclud |
|  6 Apr 2007 | 1.1 - Even more code cleaning. Rewrote tree building algorithm. Orphaned topics are now sorted as if child of the web root. No more blank line in the middle of the tree. Adding =nodiv= parameter. By TWiki:Main.StephaneLenclud |
|  6 Apr 2007 | 1.0 - More code cleaning. Testing most formatting. Better support for =web="all"=. By TWiki:Main.StephaneLenclud |
|  6 Apr 2007 | 0.9 - Support for TWiki.FormattedSearch pseudo-variables. Code cleaning in =TreePlugin.pm=. Removed some dead code. Improved documentation. By TWiki:Main.StephaneLenclud |
|  4 Apr 2007 | 0.8 - Adding =excludetopic= parameter. Adding =%<nop>TREE%= as synonym tag. Code cleaning in =TreePlugin.pm=. Fix root issue when no =topic= specified. By TWiki:Main.StephaneLenclud |
|  14 Mar 2007 | 0.7.1 - Arthur Clemens: Made =startlevel= and =stoplevel= relative to the root topic. |
|  14 Mar 2007 | 0.7 - Arthur Clemens: =web= parameter is now actually used. Added parameter =startlevel=. |
|  01 Oct 2006 | 0.6 - TWiki:Main.StephaneLenclud: adding =$index= format subsitution. Useful when used in combination with TWiki:Plugins/TreeBrowserPlugin. Also attempting to restore compatibility with Cairo, but still waiting for someone to test it.  |
|  16 Sep 2006 | 0.5 - TWiki:Main.StephaneLenclud: adding =levelprefix= parameter to unable usage in combination with TWiki:Plugins/TreeBrowserPlugin. |
|  26 Jul 2006: | 0.4 - TWiki:Main.SteffenPoulsen: Ported to TWiki 4 (Dakar). Leading text removed, less warnings, no double bracket links, CSS classnames around output. |
|  15 Feb 2002 | Alpha (0.2) release |
|  08 Feb 2002 | Internal (0.1) release |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Dependencies: | None |
|  CPAN Dependencies: | none _(test package relies on Wiki:PerlUnit)_ |
|  Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ Sandbox.HeadingOutlineSample, Sandbox.TreePluginSamples, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
gif	I.gif	r1	manage	0.8 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	L.gif	r1	manage	0.8 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	T.gif	r1	manage	0.9 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	oL.gif	r1	manage	0.9 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	oT.gif	r1	manage	0.9 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	pL.gif	r1	manage	0.9 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	pT.gif	r1	manage	0.9 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
gif	white.gif	r1	manage	0.1 K	2015-08-12 - 20:27	TWikiAdminUser	Saved by install script
This topic: TWiki > TreePlugin
Topic revision: r2 - 2024-03-02 - TWikiAdminUser
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TreePlugin.