Tree Macro
 | Provides a tree view for the structured data stored in the wiki. |
| Type | XAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | 6.3RC1+ |
Table of contents
Description
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.
Usage
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
{{/tree}}
The node label can be a link.
* [[Grandparent>>Space.Page]]
** [[Parent>>http://www.xwiki.org]]
{{/tree}}
You can use both Velocity and HTML macros inside the tree content.
{{velocity}}
{{html}}
<ul>
<li>
<a href="$xwiki.getURL('Space.Page')">$doc.parent</a>
<ul>
<li>
<a>$doc.name</a>
</li>
</ul>
</li>
</ul>
{{/html}}
{{/velocity}}
{{/tree}}
See the jsTree HTML data documentation for more information.
Dynamic Tree
You can create dynamic (interactive) trees using the reference parameter:
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:
{{velocity}}
{{html}}
#tree({
'parameter' : 'value'
})
{{/html}}
{{/velocity}}
Parameters
| Name | Description | Default Value | Since |
|---|---|---|---|
| checkboxes | Whether to display a checkbox in front of each tree node to allow the user to select multiple tree nodes. | false | 6.3RC1 |
| class | Additional CSS classes to add to the top level HTML element of the tree. | None | 6.3RC1 |
| contextMenu | Whether to show the context menu when the user right-clicks a tree node. | false | 6.3RC1 |
| dragAndDrop | Specifies if the user should be able to drag & drop tree nodes. | false | 6.3RC1 |
| edges | Whether to show the edges that connect the sibling tree nodes between themselves and with their parent. | true | 6.3RC1 |
| finder | Show 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. | false | 6.4.1 |
| icons | Whether 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. | true | 6.3RC1 |
| limit | The 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. | 15 | 8.1M2 |
| links | Specifies whether the node labels should look and behave as links (anchors). | false | 6.3RC1 |
| openTo | The 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. | None | 6.4M1 |
| reference | The 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). | None | 6.3RC1 |
| root | The 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. | None | 6.3RC1 |
| showRoot | Whether 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. | false | 7.2RC1 |
Examples
The tree macro is used by the Document Tree Macro.
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:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-tree-macro 16.10.1):
- org.xwiki.platform:xwiki-platform-webjars-api 16.10.1
- org.xwiki.platform:xwiki-platform-tree-webjar 16.10.1
- org.webjars:requirejs 2.3.7
- org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 16.10.1
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 16.10.1
- org.xwiki.rendering:xwiki-rendering-macro-html 16.10.1
- org.xwiki.platform:xwiki-platform-rendering-xwiki 16.10.1
- org.xwiki.platform:xwiki-platform-icon-script 16.10.1
