Tree Browser Plugin

<--
	Contributions to this plugin are appreciated. Please update the plugin page at
	http://twiki.org/cgi-bin/view/Plugins/TreeBrowserPlugin or provide feedback at
	http://twiki.org/cgi-bin/view/Plugins/TreeBrowserPluginDev.
	If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Acknowledgment

This plugin leverages the dTree JavaScript tree menu by Geir Landrö as well as code borrowed from TWiki:Plugins.RenderListPlugin.

Syntax Rules

Place the tag %TREEBROWSER{ parameters }% immediately before a bulleted or numbered list. The lists can be handcrafted, generated by another Plugin, a %TOC%, or the result of a FormattedSearch. The list will be rendered in a tree-like fashion (similar to the explorer folder list). Whenever a new indentation level is started, the subsequent nodes at this or a lower indentation level are shown as descendents of the preceding node. The following parameters can be used to configure the appearance of the tree:

<event> <function>[,...]

Rendering themes can be defined by <name>_THEME Plugin settings

• Each theme is defined by a comma separated list containing the render type and parameters required by that render type
• There are different render types; currently this Plugin supports tree and icon render types
• Format of the tree render type:
  • Set < name >_THEME = tree
• Format of the icon render type:
  • Set < name >_THEME = icon, [< root icon image >], [< icon image >], [< folder icon image >], [< open folder icon image >]
  • The root icon image is shown at the root of the tree, the icon image is shown at every leaf node, the folder icon image is shown at every collapsed internal node, and the open folder icon image is shown at every expanded internal node. The icon images point to files attached to TWiki topics and are referenced in the standard manner. If no path is given, the images are taken from TWikiDocGraphics.
  • If an icon image is omitted, the following defaults are chosen: , , ,

If JavaScript is not enabled, the list is rendered as usual, and the %TREEBROWSER% tag is omitted.

Bullets

• Use regular * bullets
• Start with level one
  • Increase indentation only one level at a time
    • Like this
• Decreasing indentation many levels at a time is OK
• Keep labels short as text does not wrap.
• You can specify an icon for a bullet of render type tree or icon:
  • Use any of the TWikiDocGraphics icons:
    • icon:name Followed by normal bullet text
  • Use any TreeBrowserPlugin icon:
    • icon:name.gif Followed by normal bullet text
    • Available icons: icon:globe.gif, icon:home.gif, icon:virtualhome.gif, icon:group.gif, icon:persons.gif, virtualpersons.gif, icon:person.gif, icon:virtualperson.gif, icon:email.gif, icon:trend.gif, icon:folder.gif, icon:file.gif, icon:doc.gif, icon:image.gif, icon:pdf.gif, icon:ppt.gif, icon:sound.gif, icon:xls.gif, icon:zip.gif, icon:see.gif
  • Attach the icon to the topic and refer to it, such as:
    • icon:%ATTACHURL%/myicon.gif Followed by normal bullet text
  • Refer to any icon at the beginning of the bullet using a full path or URL:
    • icon:/twiki/pub/TWiki/TWikiDocGraphics/xls.gif Followed by normal bullet text

CSS classes

A number of classes are used to facilitate look and feel customizations through CSS.

Constant class

This class won't change from one tree to the other:

• treeBrowserPlugin: given to the div element encapsulating the whole tree and javascript.

Variable classes

Those classes are prefixed with the style parameter. For clarity of the documentation we used the default dtree prefix. Variable classes allow for multiple tree style support on one page.

• dtree: given to the div element encapsulating the whole tree. Since v0.1.
• dtreeRoot: given to the div element encapsulating the root or title of the tree. Introduced in v1.1.
• dtreeLeaf: given to the div element encapsulating a tree item without children. Introduced in v0.9.
• dtreeNodeOpened: given to the div element encapsulating a tree item that is showing children. Introduced in v0.9.
• dtreeNodeClosed: given to the div element encapsulating a tree item that is hiding children. Introduced in v0.9.
• dtreeChildren: given to the div element encapsulating the children of a tree item. Changed in v0.9. Formerly clip.
• dtreeLevel0: given to the div element encapsulating the children of the tree root item. Introduced in v0.9.
• dtreeLevel1: given to the div element encapsulating the children of level 0 items. Introduced in v0.9.
• dtreeLevel2: given to the div element encapsulating the children of level 1 items. Introduced in v0.9.
• dtreeLeveln: given to the div element encapsulating the children of level n-1 items. Introduced in v0.9.
• dtreeTransluscentBackground: given to the div element used for popup translucent background. Introduced in v1.5.
• dtreeFakeItem: given to the div element simulating nodes and leaf in dtreeTransluscentBackground. It guarantees same size for the translucent background and actual dtreeChildren div. Typically you should give dtreeFakeItem the same margin and padding properties as for dtreeLeaf, dtreeNodeOpened and dtreeNodeclosed. Introduced in v1.5.

Examples

Basic

%TREEBROWSER{"file" title="[[%HOMETOPIC%][%INCLUDINGWEB% Web Home]]" shared="left"}%
   * [[WebChanges][Changes]] 
   * [[WebIndex][Index]]
   * [[WebSearch][Search]]
   * this is a very very very long text
   * Folder
      * Leaf1
      * Subfolder
         * Leaf3
      * Leaf2
   * *Webs*
%WEBLIST{"      * [[$name.%HOMETOPIC%][$name]]" }%

This tree could be used in the WebLeftBar, for example. Clicking on the plus icon next to Webs will expand the subtree below that node.

To add "collapse/expand all nodes" functionalities do something like:

<a href="javascript: tree.openAll();">open all</a> | <a href="javascript: tree.closeAll();">close all</a>
%TREEBROWSER{"file" title="[[%HOMETOPIC%][%INCLUDINGWEB% Web Home]]" shared="tree"}%
...

Menu

autotoggle example

Code

%TREEBROWSER{"thread" noroot="on" shared="menudemo" noindent="on" autotoggle="on" style="dmenu"}%
   * Vegetables
      * Carot
      * Leek
      * Tomato
      * Potato 
   * Fruits
      * Banana 
      * Grape fruit       
         * Pink
         * Yellow 
      * Peach

nodeactions example

Code

%TREEBROWSER{"thread" noroot="on" shared="memenudemo" noindent="on" style="dmenu" nodeactions="onmouseover open, onclick close"}%
   * Vegetables
      * Carot
      * Leek
      * Tomato
      * Potato 
   * Fruits
      * Banana
      * Grape fruit       
         * Pink
         * Yellow 
      * Peach

Pop-up example

Code

%TREEBROWSER{"thread" noroot="on" shared="memenudemo" noindent="on" style="dmenu" nodeactions="onmouseover open, onclick close", closesamelevel="on" popup="on" popupoffset="-10,-4" }%
   * Vegetables
      * Carot
      * Leek
      * Tomato
      * Potato 
   * Fruits
      * Banana
      * Grape fruit       
         * Pink
         * Yellow 
      * Peach

Simulated

Pop-up menu opacity example

Code

%TREEBROWSER{"thread" noroot="on" shared="opacitynotabledemo" noindent="on" style="smenu" nodeactions="onmouseover open, onclick close" popup="on" closesamelevel="on" closepopupdelay="100" firstpopupoffset="-60,0" popupoffset="-20,0" useopacity="on"}%
   * <a>Vegetables</a>
      * <a>Carot</a>
      * <a>Leek</a>
      * <a>Tomato</a>
      * <a>Potato</a>
   * <a>Fruits</a>
      * <a>Banana</a>
         * <a>Green</a>
         * <a>Yellow</a> 
      * <a>Grape fruit</a>       
         * <a>Pink</a>
         * <a>Yellow</a> 
      * <a>Peach</a>

Simulated

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %TREEBROWSERPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Renders a list as a collapsable/expandable tree.

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

• Themes are named <SOMETHING>_THEME and contain a comma delimited list of render type with parameters:
  • Set THREAD_THEME = tree
  • Set HOME_THEME = icon,
  • Set ORG_THEME = icon, , , ,
  • Set GROUP_THEME = icon, tip.gif, , ,
  • Set EMAIL_THEME = icon,
  • Set TREND_THEME = icon,
  • Set FILE_THEME = icon,
  • Set DIR_THEME = icon, ,
  • Set FORUM_THEME = icon, group.gif, index.gif, indexlist.gif, indexlist.gif

Plugin 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.

Show details Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

Known issues

• PatternSkin prevents javascript to determine menu position in topic content. Use firstpopupoffset="-163,0" as a workaround.
• NatSkin CSS natMainContent overflow:hidden causes z-index bug in FireFox. Workaround by removing or overriding overflow:hidden for natMainContent.
• dtreeTranslucentBackground only works for pop-up and not level 0. Sizing issue...
• Pop-up sub-menu won't work on IE for dmenu style. Workaround by using smenu.

Planned Enhancements

See TWiki:Plugins.TreeBrowserPluginDev.

Plugin Info

Plugin Author:	TWiki:Main.ThomasWeigert & TWiki:Main.StephaneLenclud
Copyright:	© 2000-2003 TWiki:Main.AndreaSterbini, © 2001-2004 TWiki:Main.PeterThoeny, © 2004 TWiki:Main.ThomasWeigert, © 2006-2007 TWiki:Main.StephaneLenclud, © 2000-2014 TWiki:TWiki.TWikiContributor
Sponsor:	Wave Systems Corp. for Item7404
License:	GPL (GNU General Public License)
Plugin Version:	2014-09-29

Show Change History Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

2014-09-29:	TWikibug:Item7554: The warning message of an indentation leap has been demoted to a debug message so that you can avoid warning message flood by such topics accessed a lot -- TWiki:Main.HideyoImazu
2014-01-02:	TWikibug:Item7404: Fix to even spacing between icon and text; remove dotted underline of +/- node icon links -- TWiki:Main.PeterThoeny
2013-12-31:	TWikibug:Item7404: Support for TWiki Doc Graphics icons using icon:name syntax; if specified, use icon:name instead of open/close folder icons -- TWiki:Main.PeterThoeny
2013-01-23:	TWikibug:Item6977: This topic caused timeout on a large site, which is fixed
2011-01-19:	TWikibug:Item6638: More doc fixes
2010-07-25:	TWikibug:Item6530: Doc fixes
29 Mar 2007:	(v1.8) - Improved smenu CSS and fixing warning. By Stephane Lenclud.
18 Mar 2007:	(v1.7) - Improved smenu CSS, resolved highlighting gap issue . Now closing sub-menu when highlighting leaf. By Stephane Lenclud.
18 Mar 2007:	(v1.6) - Sub-menus now working in IE with smenu style. Closing sub-menu when going back one level with mouse cursor. By Stephane Lenclud.
18 Mar 2007:	(v1.5) - Adding useopacity parameter. Adding smenu.css. By Stephane Lenclud.
16 Mar 2007:	(v1.4) - Adding firstpopupoffset allowing workaround for PatternSkin problem. By Stephane Lenclud.
14 Mar 2007:	(v1.3) - Adding popup, closepopudelay and popupoffset parameters. Implemented pop-up menu. Improved dmenu.css. By Sephane Lenclud.
11 Mar 2007:	(v1.2) - Adding nodeactions parameter. Improved dmenu.css. By Stephane Lenclud.
10 Mar 2007:	(v1.1) - Adding autotoggle parameter. It's useful for menu style. Improved dmenu.css. Added dtreeRoot CSS class. By Stephane Lenclud.
09 Mar 2007:	(v1.0) - Improved CSS with variable class name allowing for multiple tree with different style on the same topic. Now bullet icon: supports full URL or URI. By Stephane Lenclud.
09 Mar 2007:	(v0.9) - Adding style parameter. Improved CSS. Fixes extra '\n' in dot pm. By Stephane Lenclud.
07 Mar 2007:	(v0.8) - Adding noroot and warn parameters. Now using preRenderingHandler instead of the deprecated startRenderingHandler . %TREEBROWSER% are hidden if there is no tree to render. Fixes TOC icons problem with TWiki:Plugins.NatSkin. By Stephane Lenclud.
01 Oct 2006:	(v0.7) - Adding useplusminus , noindent and nocss parameters. By Stephane Lenclud.
17 Sep 2006:	(v0.6) - Adding closesamelevel and uselines functionalities, fix rendering issues with Firefox and pattern skin, fix warnings in apache error logs. By Stephane Lenclud
12 Apr 2006:	(v0.5) - Minor update for TWiki:Codev.TWikiRelease04x00
16 Sep 2005:	(v0.4) - Fix bug in openAll and openTo functions
06 Sep 2005:	(v0.3) - Adopt the rendering themes from TWiki:Plugins.RenderListPlugin
05 Sep 2005:	(v0.2) - Support sharing of tree state across topics. If JavaScript is not enabled, render the list in standard fashion. Correct user input error containig a line that is too deeply indented.
04 Sep 2005:	(v0.1) - Initial version

<--/twistyPlugin-->

TWiki Dependency:	$TWiki::Plugins::VERSION 1.024
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005, 5.8.7
License:	GPL (GNU General Public License)
Benchmarks:	GoodStyle n%, FormattedSearch n%, TreeBrowserPlugin n%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/TreeBrowserPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/TreeBrowserPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/TreeBrowserPluginAppraisal

Related Topics: TWiki:Plugins.RenderListPlugin, TWiki:Plugins.TreePlugin