TIP TreeBrowserPlugin is not installed on Foswiki.org.

Tree Browser Plugin

Renders a bulleted or numbered list as a collapsible/expandable tree of nodes.

Acknowledgment

This plugin leverages the dTree JavaScript tree menu by Geir Landrö as well as code borrowed from Foswiki:Extensions.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:

Parameters

  • The following standard attributes are recognized
Parameter Description Default
"name" or
theme="name"
Select a rendering theme none
title Required. This text serves as the root of the tree none
openAll If on, the tree is shown fully expanded. off
openTo Must be an integer. If present, the tree is expanded to the given node, as numbered from the root. 0
shared Must be a string. If present, the state of the tree is shared across all trees using this string. For example, if the tree is used in the WebLeftBar, the state will hold at all topics with this WebLeftBar. It's basically the name of the JavaScript object representing your tree. none
uselines Set to false if you don't want to show lines linking nodes and leafs in the tree true
useplusminus Set to false if you don't want to show '-' and '+' signs. One can use something like onclick='javascript: tree.o($index);' in the tree item to trigger opening/closing of a node. true
noindent Set to true to show children at the level of their parent. It suppresses children indentation. Enabling noindent will disable uselines and useplusminus. false
nocss Set to true to prevent inclusion of dtree.css. false
closesamelevel If true only one node within a parent can be expanded at the same time. openAll() and closeAll() functions do not work when this is enabled. false
noroot Prevents rendering of the title line. Useful if you don't want to show any title. false
warn Text to be displayed if no tree was found. none
style Name of the CSS file to include without the .css extension. The CSS file must be attached to this topic. dtree
autotoggle Set to on will enable node open/close when clicking the node item. Typically used for menu style tree along with noindent. off
nodeactions Defines node functionality in a comma separated list of HTML event and dTree function. Typically used for menu style tree along with noindent. Format:
<event> <function>[,...]
event is an HTML event e.g. onclick, ondblclick, onmouseover, onmouseout...
function is one of the three dTree functions: open, close, toggle
none
popup Set to on to enable pop-up menu mode. Typically used with closesamelevel. See pop-up menu example. off
closepopupdelay Pop-up mode only. Delay in millisecond before all popup close once the mouse cursor has left the menu structure. 1000
popupoffset Provides x and y offset from parent node for pop-up menus. Allows for fine tunning of pop-up position. 0,0
firstpopupoffset Provides x and y offset for first level pop-up menus. Introduce as a workaround for PatternSkin issues. 0,0
useopacity Used to generate extra dtreeTransluscentBackground div. Enables popup with translucent background and opaque text. off

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 wiki topics and are referenced in the standard manner. If no path is given, the images are taken from DocumentGraphics.
    • If an icon image is omitted, the following defaults are chosen: empty.gif, page.gif, folder.gif, folderopen.gif

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 fine
  • Keep labels short as text does not wrap.
  • You can specify an icon for a bullet of render type tree or icon:
    • Attach the icon to a topic, e.g. myicon.gif, or
    • Use one of the existing icons: globe.gif %ATTACHURL%/globe.gif, home.gif %ATTACHURL%/home.gif, virtualhome.gif %ATTACHURL%/virtualhome.gif, group.gif %ATTACHURL%/group.gif, persons.gif %ATTACHURL%/persons.gif, virtualpersons.gif virtualpersons.gif, person.gif %ATTACHURL%/person.gif, virtualperson.gif %ATTACHURL%/virtualperson.gif, email.gif %ATTACHURL%/email.gif, trend.gif %ATTACHURL%/trend.gif, folder.gif %ATTACHURL%/folder.gif, file.gif %ATTACHURL%/file.gif, doc.gif %ATTACHURL%/doc.gif, image.gif %ATTACHURL%/image.gif, pdf.gif %ATTACHURL%/pdf.gif, ppt.gif %ATTACHURL%/ppt.gif, sound.gif %ATTACHURL%/sound.gif, xls.gif %ATTACHURL%/xls.gif, zip.gif %ATTACHURL%/zip.gif, see.gif %ATTACHURL%/see.gif
    • Refer to an attached icon at the beginning of the bullet with:
      • icon:myicon.gif Followed by normal bullet text
    • Refer to any icon at the beginning of the bullet using a full path or URL:
      • icon:http://foswiki.org/pub/System/DocumentGraphics/xls.png 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
   * *Webs*
%WEBLIST{"      * [[$name.%HOMETOPIC%][$name]]"}%
generates
If installedSimulated
%TREEBROWSER{"file" title="Extensions Web Home" shared="basicdemo"}%

open all | close all

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"}%
...

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

If installedSimulated
%TREEBROWSER{"thread" noroot="on" shared="realmenu" 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%

  • Debug plugin: (See output in working/logs/debug.log or your configured debug log location.)
    • 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, home.gif
    • Set ORG_THEME = icon, base.gif, home.gif, person.gif, persons.gif
    • Set GROUP_THEME = icon, tip.gif, page.gif, person.gif, group.gif
    • Set EMAIL_THEME = icon, email.gif
    • Set TREND_THEME = icon, trend.gif
    • Set FILE_THEME = icon, empty.gif
    • Set DIR_THEME = icon, empty.gif
    • Set FORUM_THEME = icon, group.gif, index.gif, indexlist.gif, indexlist.gif

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

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 Foswiki:Development.TreeBrowserPlugin.

Plugin Info

Change History:  
03 Sep 2015: (V2.2) - Foswikitask:Item4192: Add VarTREEBROWSER topic
Foswikitask:Item2941: Close out some old pending work.
Foswikitask:Item13656: Update for newer perls, other minor doc issues.
27 Oct 2010: (v2.1) - Minor rebranding from 'TWiki'. By Dan Dascalescu.
10 Nov 2009: (v2.0) - Fixed version numbering for configure. By Ingo Kappler.
20 Feb 2009: (v1.9) - Foswiki port. By Stephane Lenclud.
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 Stephane 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 Foswiki:Extensions.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 Foswiki:Extensions.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
Development: Foswiki:Development.TreeBrowserPlugin

I Attachment Action Size Date Who Comment
TreeBrowserPlugin.md5md5 TreeBrowserPlugin.md5 manage 174 bytes 03 Sep 2015 - 03:18 GeorgeClark  
TreeBrowserPlugin.sha1sha1 TreeBrowserPlugin.sha1 manage 198 bytes 03 Sep 2015 - 03:18 GeorgeClark  
TreeBrowserPlugin.tgztgz TreeBrowserPlugin.tgz manage 43 K 03 Sep 2015 - 03:17 GeorgeClark  
TreeBrowserPlugin.zipzip TreeBrowserPlugin.zip manage 54 K 03 Sep 2015 - 03:17 GeorgeClark  
TreeBrowserPlugin_installerEXT TreeBrowserPlugin_installer manage 7 K 03 Sep 2015 - 03:18 GeorgeClark  
base.gifgif base.gif manage 1 K 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
cd.gifgif cd.gif manage 239 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
dmenu.csscss dmenu.css manage 2 K 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
doc.gifgif doc.gif manage 922 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
dtree.csscss dtree.css manage 988 bytes 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
dtree.jsjs dtree.js manage 29 K 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
email.gifgif email.gif manage 183 bytes 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
empty.gifgif empty.gif manage 62 bytes 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
file.gifgif file.gif manage 151 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
folder.gifgif folder.gif manage 372 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
folderopen.gifgif folderopen.gif manage 376 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
globe.gifgif globe.gif manage 1 K 11 Feb 2014 - 08:53 MichaelDaum Saved by install script
group.gifgif group.gif manage 162 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
home.gifgif home.gif manage 172 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
image.gifgif image.gif manage 943 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
imgfolder.gifgif imgfolder.gif manage 622 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
join.gifgif join.gif manage 69 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
joinbottom.gifgif joinbottom.gif manage 66 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
line.gifgif line.gif manage 66 bytes 11 Feb 2014 - 08:53 MichaelDaum Saved by install script
minus.gifgif minus.gif manage 86 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
minusbottom.gifgif minusbottom.gif manage 85 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
musicfolder.gifgif musicfolder.gif manage 633 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
nolines_minus.gifgif nolines_minus.gif manage 861 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
nolines_plus.gifgif nolines_plus.gif manage 870 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
page.gifgif page.gif manage 582 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
pdf.gifgif pdf.gif manage 938 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
person.gifgif person.gif manage 153 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
persons.gifgif persons.gif manage 164 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
plus.gifgif plus.gif manage 89 bytes 11 Feb 2014 - 08:53 MichaelDaum Saved by install script
plusbottom.gifgif plusbottom.gif manage 88 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
ppt.gifgif ppt.gif manage 921 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
question.gifgif question.gif manage 1 K 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
see.gifgif see.gif manage 81 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
smenu.csscss smenu.css manage 3 K 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
sound.gifgif sound.gif manage 166 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
trash.gifgif trash.gif manage 1 K 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
tree.jpgjpg tree.jpg manage 7 K 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
trend.gifgif trend.gif manage 149 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
virtualhome.gifgif virtualhome.gif manage 162 bytes 11 Feb 2014 - 08:53 MichaelDaum Saved by install script
virtualperson.gifgif virtualperson.gif manage 149 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
virtualpersons.gifgif virtualpersons.gif manage 160 bytes 11 Feb 2014 - 08:51 MichaelDaum Saved by install script
xls.gifgif xls.gif manage 918 bytes 11 Feb 2014 - 08:50 MichaelDaum Saved by install script
zip.gifgif zip.gif manage 940 bytes 11 Feb 2014 - 08:52 MichaelDaum Saved by install script
Topic revision: r9 - 03 Sep 2015, GeorgeClark
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy