Tree Macro

Last modified by Admin on 2024/05/11 01:56

chart_organisationProvides a tree view for the structured data stored in the wiki.
Developed by

XWiki Development Team

1 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard



Installable with the Extension Manager


You can use the tree macro to create a tree view for the structured data you have in your wiki. It uses the Tree Widget which is based on jsTree.


Wiki Macro

Static Tree

You can create static trees by putting nested unordered lists inside the macro content. Here's an example using wiki syntax:

* Grandparent
** Parent
*** Child

The node label can be a link.

* [[Grandparent>>Space.Page]]
** [[Parent>>]]

You can use both Velocity and HTML macros inside the tree content.

    <a href="$xwiki.getURL('Space.Page')">$doc.parent</a>

See the jsTree HTML data documentation for more information.

Dynamic Tree

You can create dynamic (interactive) trees using the reference parameter:

{{tree reference="Space.MyTreeDefinition" /}}

Checkout the Tree Widget documentation for more information on how a dynamic tree is defined, and follow the Creating a Tree View tutorial to create your own dynamic tree.

Velocity Macro

Starting with version 7.4M1 there is also a Velocity macro available. You can use it to create a dynamic tree.

  'parameter' : 'value'

In order to use it you have to include the tree_macros.vm Velocity template (where the macro is defined). Here's how you can do it from the content of a wiki page:

{{template name="tree_macros.vm" /}}

  'parameter' : 'value'


NameDescriptionDefault ValueSince
checkboxesWhether to display a checkbox in front of each tree node to allow the user to select multiple tree nodes.false6.3RC1
classAdditional CSS classes to add to the top level HTML element of the tree.None6.3RC1
contextMenuWhether to show the context menu when the user right-clicks a tree node.false6.3RC1
dragAndDropSpecifies if the user should be able to drag & drop tree nodes.false6.3RC1
edgesWhether to show the edges that connect the sibling tree nodes between themselves and with their parent.true6.3RC1
finderShow a text input that can be used to find tree nodes. The input is displayed above the tree and offers suggestions as you type based on the content of the tree. When a suggestion is selected the tree is expanded up to the corresponding node.false6.4.1
iconsWhether to show the tree node icons or not. You may want to hide the icons if all the tree nodes are of the same type or if you want to win some horizontal space.true6.3RC1
limitThe maximum number of child nodes to display when expanding a parent node for the first time. The rest of the child nodes are accessible through a "more ..." link. This parameter is basically used to paginate the child nodes and thus helps the tree scale when the number of child nodes is large. The tree passes this parameter to the tree source so it works only with dynamic trees whose source implements child count limit.158.1M2
linksSpecifies whether the node labels should look and behave as links (anchors).false6.3RC1
openToThe id of the node to open the tree to. All the ancestors of the specified node, up to the root of the tree, will be opened also.None6.4M1
referenceThe reference to the resource that describes the tree structure and its context menu and which is called to perform the actions on the tree nodes. This resource is used to load the tree dynamically (on demand) when a tree node is opened and to ask for the context menu when the user right-clicks on a tree node that has it. So the resource is not static. For static trees you should use the macro content instead. The reference can be a document reference or an URL/path (prefix the URL with path: in that case).None6.3RC1
rootThe root node id. This is useful if you want to display only the descendants of a given node (which is the specified root). Depending on the value of the showRoot parameter, the tree displays the children of the root node on the first level or the root node itself. The entire tree is displayed if the root node is not specified.None6.3RC1
showRootWhether to show the root node or not. The root node is not shown by default because it is usually implied from the context where the tree is displayed (e.g. a label before the tree). There are some cases though when you may want to display the root node: to be able to create a new node under the root.false7.2RC1


The tree macro is used by the Document Tree Macro.

{{tree reference="XWiki.DocumentTree" /}}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki


Dependencies for this extension (org.xwiki.platform:xwiki-platform-tree-macro 16.3.1):

Get Connected