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
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:
| 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 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
- 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:
%ATTACHURL%/globe.gif, 
%ATTACHURL%/home.gif, 
%ATTACHURL%/virtualhome.gif, 
%ATTACHURL%/group.gif, 
%ATTACHURL%/persons.gif, 
virtualpersons.gif, 
%ATTACHURL%/person.gif, 
%ATTACHURL%/virtualperson.gif, 
%ATTACHURL%/email.gif, 
%ATTACHURL%/trend.gif, %ATTACHURL%/folder.gif, 
%ATTACHURL%/file.gif, 
%ATTACHURL%/doc.gif, 
%ATTACHURL%/image.gif, 
%ATTACHURL%/pdf.gif, 
%ATTACHURL%/ppt.gif, 
%ATTACHURL%/sound.gif, 
%ATTACHURL%/xls.gif, 
%ATTACHURL%/zip.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:https://wiki.planta.de/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
* *Webs*
%WEBLIST{" * [[$name.%HOMETOPIC%][$name]]"}%
generates
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)
- 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
- Download the zip file.
- Unzip
TreeBrowserPlugin.zip in your twiki installation directory. Content: | File: | Description: |
data/TWiki/TreeBrowserPlugin.txt | Plugin topic |
lib/TWiki/Plugins/TreeBrowserPlugin.pm | Plugin Perl module |
pub/TWiki/TreeBrowserPlugin/dtree.css | part of dtree |
pub/TWiki/TreeBrowserPlugin/dmenu.css | Menu CSS |
pub/TWiki/TreeBrowserPlugin/smenu.css | Nicer menu CSS |
pub/TWiki/TreeBrowserPlugin/dtree.js | part of dtree |
pub/TWiki/TreeBrowserPlugin/base.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/cd.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/empty.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/folder.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/folderopen.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/globe.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/imgfolder.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/join.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/joinbottom.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/line.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/minus.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/minusbottom.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/musicfolder.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/nolines_minus.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/nolines_plus.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/page.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/plus.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/plusbottom.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/question.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/trash.gif | part of dtree |
pub/TWiki/TreeBrowserPlugin/doc.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/email.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/file.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/group.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/home.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/image.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/pdf.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/person.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/persons.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/ppt.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/see.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/sound.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/trend.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/virtualhome.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/virtualperson.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/virtualpersons.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/xls.gif | icons from RenderListPlugin |
pub/TWiki/TreeBrowserPlugin/zip.gif | icons from RenderListPlugin |
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
Related Topics: TWiki:Plugins.RenderListPlugin,
TWiki:Plugins.TreePlugin
gif 
css 
js 
jpg 
Users
Groups
Search
Changes
Notifications
Statistics
Preferences
