Document Tree Macro
 | Macro used to display a hierarchy of XWiki documents by using a tree. |
| Type | XAR |
| Category | Macro |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | 6.3RC1+ |
Table of contents
Description
Displays a hierarchy of documents (or any other entities such as spaces, wikis, objects, etc) using the Tree Macro.
Usage
WYSIWYG Editor
You can insert this macro from the WYSIWYG Editor. Look for "Page Tree" in the list of macros.
Wiki Macro
Parameters
| Name | Description | Default Value |
|---|---|---|
| checkboxes | Whether to display a checkbox in front of each tree node to allow the user to select multiple tree nodes. | false |
| compact | If you have limited horizontal space available then you should probably set this to true. The effect is that the node icons and the edges that connect them will be hidden. Some special styles will also be applied to ensure the tree takes less horizontal space while keeping the node labels fully visible. | false |
| exclusions | The list of nodes to exclude from the tree. The nodes are specified by their id. At the moment this parameter is taken into account only when hierarchyMode="reference" (the default value) and can be used to exclude only wiki and document nodes. The wiki rendering macro expects a comma-separated list, e.g.: exclusions="wiki:dev,document:someWiki:Path.To.Page" . The Velocity macro expects an actual Set<String>, e.g.: {'exclusions': $collectiontool.set} | None |
| filterByClass | Show only the documents that have an object of the specified type. The value of this parameter is the full name of an XWiki document that holds a class definition. For example, 'Blog.CategoryClass' can be used to show only the documents that represent blog categories. Leave this parameter empty if you don't want to restrict the type of documents shown in the tree. | None |
| filterHiddenDocuments | Set this parameter to false if you want to include the hidden documents in the tree. Otherwise, if the value is true, the hidden documents are excluded or included based on current user's preferences. | true |
| 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 |
| hierarchyMode | Specifies which hierarchy to use between documents. Possible values are "reference" (default) and "parentchild". If "reference" is used then the document hierarchy is defined using only the document reference, especially the nested spaces component of the document reference. If "parentchild" is used then the hierarchy is based on the parent/child relationship defined by the "parent" document field from the database. | reference |
| 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. In case there is only one child node remaining, the "more ..." link is replaced by that child node. This parameter is basically used to paginate the child nodes and thus helps the tree scale when the number of child nodes is large. | 15 |
| links | Specifies whether the node labels should look and behave as links (anchors). | true |
| 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. The format of the node id is the one used for the root parameter. Example: document:wiki:space1.space2.page | None |
| readOnly | Should the user be able to modify the tree structure, provided she has the necessary rights? Note that the changes you make to the tree structure are currently not saved. This is something we'd like to implement in the future. | true |
| 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. The format of a node identifier is entityType:entityReference (see how to get the reference of a page), where the entity type can be for instance wiki, space, document. E.g.: wiki:xwiki, space:xwiki:Main, document:xwiki:Main.WebHome. Note that if you use an Entity Type other than document you must also set the showXXX parameter to true (where XXX is the Entity Type), e.g. showSpaces=true | None |
| showAttachments | Whether to show the document attachments or not. | true |
| showChildDocuments | Whether to show the child documents based on the document parent field. Deprecated. Use the hierarchyMode parameter instead. | true |
| showClassProperties | Whether to show the class properties for documents that define classes. | false |
| showDocumentTitle | Whether to show the rendered document translated title instead of the document name when displaying a document node. If this parameter is set to true then the child nodes are sorted by their raw translated title, with a fall-back on the raw default title and then on the document name (if the raw titles are empty). Note that the rendered title may be different than the raw title if the title is dynamic (i.e. has Velocity code) so the child nodes may not be sorted correctly if some have dynamic titles. The child nodes are sorted by document name when this parameter is set to false. | true |
| showObjects | Whether to show the document objects or not. | false |
| showOnlyViewable | Show only the wiki, space and document nodes for which the current user has view right. If this is set to false then the wiki, space and document nodes that are not viewable by the current user are listed in the tree using their names. The user won't be able to see their content by following their links though (the user will just be aware of their existence). | true |
| 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 |
| showSpaces | Whether to show the space nodes or not. The documents are grouped by space if the space nodes are displayed. | false |
| showTranslations | Whether to show the document translations or not. | true |
| showWikis | Whether to show the wiki nodes or not. This can be used only on the main wiki and if the tree source has been saved with programming rights. | false |
| showWikiPrettyName | Show the wiki pretty name instead of the wiki id when displaying a wiki node. | true |
| sortDocumentsBy | XWiki 16.10.3+, 17.0.0+ The document field used to sort the child documents, followed by the sort order. The following document fields are currently supported: name, title, date (last modification date) and creationDate. You can optionally indicate the sort order: asc (ascending) or desc (descending). Defaults to title:asc when showDocumentTitle is true, and name:asc otherwise. | title:asc |
Velocity Macro
There is also a Velocity macro available.
'parameter' : 'value'
...
})
In order to use it you have to include the documentTree_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}}
#documentTree({})
{{/html}}
{{/velocity}}
Examples
Empty Document Tree
When the tree is empty the following message is displayed:
Children Pages
Displays children pages of the current page:
See also the Children Macro.
Nested Document Tree
This is the same tree you get in the Document Index Tree View.
Nested Space Tree
Parent-Child Document Tree
This is useful if you want to organize your documents independent of their location (reference). For this you'll have to use the parent document field (from the database).
Parent-Child Mixed With Space Grouping
Navigation Panel
Full Entity Tree
showChildDocuments="false" showObjects="true" showClassProperties="true" /}}
Subtree with Checkboxes
Custom Document Tree
If the available document tree parameters are not enough to adjust the document tree to your needs then you may have to create a custom document tree. One way to do this is to create a new page that reuses some of the Velocity macros from XWiki.DocumentTreeMacros and then pass it in the reference parameter of the Tree Macro:
Check the following examples of custom tree definitions.
Exclude nodes based on their ids
{{velocity output="false"}}
#macro (filterChildren $children)
#set ($excludes = ['xwiki:Main.WebHome', 'xwiki:XWiki.WebHome'])
#set ($filteredChildren = [])
#foreach ($child in $children)
#if (!$excludes.contains($child.data.id))
#set ($discard = $filteredChildren.add($child))
#end
#end
#set ($discard = $children.clear())
#set ($discard = $children.addAll($filteredChildren))
#end
{{/velocity}}
{{velocity wiki="false"}}
#if ($xcontext.action == 'get')
#updateDocTreeConfigFromRequest
#if ($request.data == 'children')
#set ($children = $NULL)
#getChildren($request.id $children)
#if ($children)
#filterChildren($children)
#set ($discard = $response.setContentType('application/json'))
$jsontool.serialize($children)
#else
$response.sendError(404);
#end
#else
## Continue with the default behaviour.
#handleDocumentTreeRequest
#end
#end
{{/velocity}}
Debugging
If you see a spinning wheel and no data displayed in your custom tree UI, it means your page returning your custom data is not returning data in the right format. You can check this by opening the your browser dev tools and find the request to your custom page. Then check the response you send back and verify the data.
For Developers
XWiki.DocumentTree
When calling XWiki.DocumentTree to retrieve the attachments. For instance http://localhost:8080/xwiki/bin/get/XWiki/DocumentTree?outputSyntax=plain&language=en&showTranslations=false&showWikis=true&data=children&id=attachments%3Axwiki%3ASandbox.WebHome, the response is for the form:
{
"id": "attachment:xwiki:Sandbox.WebHome@XWikiLogo.png",
"text": "XWikiLogo.png",
"icon": "fa fa-file-image-o",
"children": false,
"data": {
"id": "xwiki:Sandbox.WebHome@XWikiLogo.png",
"type": "attachment",
"validChildren": [],
"hasContextMenu": true,
"draggable": true,
"canRename": true,
"canDelete": true,
"canMove": true,
"canCopy": true,
"deleteURL": "/xwiki/bin/delattachment/Sandbox/WebHome/XWikiLogo.png",
"mimetype": "image/png"
},
"a_attr": {
"href": "/xwiki/bin/download/Sandbox/WebHome/XWikiLogo.png?rev=1.1"
}
}
]
The data key contains the mimetype field, containing the mimetype of the listed document.
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-index-tree-macro 17.0.0):
- org.xwiki.platform:xwiki-platform-index-tree-api 17.0.0
- org.xwiki.platform:xwiki-platform-tree-macro 17.0.0
- org.xwiki.platform:xwiki-platform-icon-script 17.0.0
- org.xwiki.platform:xwiki-platform-icon-fontawesome 17.0.0
- org.xwiki.platform:xwiki-platform-security-authorization-script 17.0.0
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 17.0.0
- org.xwiki.platform:xwiki-platform-rendering-macro-include 17.0.0
- org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 17.0.0
- org.xwiki.platform:xwiki-platform-extension-handler-xar 17.0.0
