"tree" Macro
Reference
Description
The tree macro displays structured data as a tree, with the Tree Widget, itself based on jsTree. The tree is either static, described by the macro content, or dynamic, loaded node by node from a resource given in the reference parameter.
Page authors who only need a static tree written as a wiki list can read the user page of the "tree" macro. The "documentTree" macro is a dynamic tree built on this macro.
Usage
The macro is standalone only and is listed in the Navigation category.
Static Tree
The content is parsed in the syntax of the page and has to produce nested unordered lists. A wiki list is enough:
{{tree}}
* Grandparent
** Parent
*** Child
{{/tree}}The content can also be generated, with the velocity and html macros for instance. The HTML then follows the jsTree HTML data format, which gives access to node attributes such as the jstree-open class that displays a node opened.
Dynamic Tree
{{tree reference="Space.MyTreeDefinition"/}}The reference parameter designates the resource that answers the requests of the tree: the children of a node when it is opened, the path to a node, the context menu, the finder suggestions. The Tree Widget documentation describes what such a resource has to answer, and the Creating a Tree View tutorial builds one step by step.
The exclusions, limit, root and showRoot parameters are not handled by the macro itself: they are forwarded to the resource as request parameters, so they only have an effect on a dynamic tree whose resource supports them.
Velocity Macro
A dynamic tree can also be displayed from a script, with the #tree Velocity macro of the tree_macros.vm template. It takes the parameters below as a map, exclusions being a set of node ids instead of a comma-separated list.
{{template name="tree_macros.vm"/}}
{{velocity}}
{{html}}
#tree({
'reference': 'Space.MyTreeDefinition',
'links': true
})
{{/html}}
{{/velocity}}Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| content | no | wiki syntax | none | Nested unordered lists describing a static tree. Leave it empty for a dynamic tree. In the WYSIWYG editor, a tree without content displays a placeholder message. |
| checkboxes | no | true, false | false | Whether to display a checkbox in front of each node, to let the user select several nodes. |
| class | no | CSS class names separated by spaces | xtree | The value of the class attribute of the top level element of the tree. It replaces the default value: keep xtree in it, as in class="xtree myTree", otherwise the content is displayed as a plain list. |
| contextMenu | no | true, false | false | Whether to show the context menu when the user right-clicks a node. The menu is requested from the resource of a dynamic tree. |
| dragAndDrop | no | true, false | false | Whether the user can drag and drop the nodes. |
| edges | no | true, false | true | Whether to display the lines connecting the nodes. |
| exclusions | no | a comma-separated list of node ids | none | The nodes to leave out of the tree. It has no effect on a static tree. |
| finder | no | true, false | false | Whether to display a search field above the tree. It suggests nodes as the user types and opens the tree to the selected one. |
| icons | no | true, false | true | Whether to display the node icons. Hiding them makes sense when all the nodes are of the same type, or to save horizontal space. |
| limit | no | a positive integer | 15 | The maximum number of child nodes displayed when a node is opened for the first time, the others being reached through a "more ..." link. It only works on a dynamic tree whose resource implements this pagination. |
| links | no | true, false | false | Whether the node labels look and behave as links. |
| openTo | no | a node id | none | The node to open the tree to. All its ancestors, up to the root of the tree, are opened as well. |
| reference | no | a page reference, or path: followed by a URL or a path | none | The resource that provides the nodes of a dynamic tree and its context menu, and that performs the actions on the nodes. |
| root | no | a node id | none | The node whose descendants are displayed. Without it the resource decides where the tree starts. |
| showRoot | no | true, false | false | Whether to display the root node itself, above its children. It is hidden by default because the context of the tree usually implies it. Showing it is useful to let the user create a node directly under the root. |
Examples
Generate a Static Tree with Velocity and HTML
The first node is displayed opened, thanks to the jstree-open class.
{{tree links="true"}}
{{velocity}}
{{html}}
<ul>
<li class="jstree-open">
<a href="$xwiki.getURL('Sandbox.WebHome')">Sandbox</a>
<ul>
<li><a>$escapetool.xml($doc.name)</a></li>
</ul>
</li>
</ul>
{{/html}}
{{/velocity}}
{{/tree}}Display the Page Tree from Its Resource
XWiki.DocumentTree is the resource behind the "documentTree" macro. It supports root, showRoot and limit.
{{tree reference="XWiki.DocumentTree" root="document:xwiki:Sandbox.WebHome" showRoot="true" links="true"/}}
