Document Tree Macro

Document Tree Macro is provided by the Index Application and displays the hierarchy of wiki documents using the Tree Macro. The Tree Macro uses the Tree Widget which is based on jstree.

Usage

{{documentTree checkboxes="<true|false>" compact="<true|false>" filterByClass="<WikiClassName>"
filterHiddenDocuments="<true|false>" finder="<true|false>" hierarchyMode="<reference|parentchild>"
limit="<number>" links="<true|false>" openTo="<NodeID>" readOnly="<true|false>" root="<RootNodeID>"
showAttachments="<true|false>" showClassProperties="<true|false>" showDocumentTitle="<true|false>"
showObjects="<true|false>" showOnlyViewable="<true|false>" showRoot="<true|false>" showSpaces="<true|false>"
showTranslations="true|false" showWikis="<true|false>" showWikiPrettyName="<true|false>" /}}

Parameters

NameOptionalDescriptionDefault Values
checkboxesYesWhether to display a check-box before each tree node in order to allow selecting multiple tree nodesfalse
compactYesWhether to hide the node icons and the edges that connect them. Some special styles will also be applied to ensure the tree takes less horizontal space while keeping the node labels fully visible. This option is useful when having limited horizontal space available.false
filterByClassYesDisplay only documents that have an object of the specified type. The value should be the full name of an XWiki document that holds a class definition.
Leave this parameter empty in order to have no restriction.
None
filterHiddenDocumentsYesIf you want to include the hidden documents in the tree, you should set this parameter to false. Otherwise, if the value is true, the hidden documents are excluded or included based on current user preferences.true
finderYesDisplays a text input with an additional suggest widget above the tree that can be used to find tree nodes. When a suggestion is selected, the tree is expanded up to the corresponding node.false
hierarchyModeYes

Specifies which hierarchy to use between documents:

  • "reference" (default) - the document hierarchy is defined using only the document reference, especially the nested spaces component of the document reference
  • "parentchild" - the hierarchy is based on the parent/child relationship defined by the "parent" document field from the database
reference
linksYesWhether the node labels should look and behave as anchors.true
limitYesThe maximum number of child nodes to display when expanding a parent node for the first time. The remaining 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
openToYesThe 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.None
readOnlyYesA flag stating whether the user should be able to modify the tree structure, provided he/she has the necessary rights.true
rootYesThe root node ID. This parameter is useful when wanting to display only the descendants of a given node.
The tree displays the first level children but not the root node itself.
In case the root node is not specified, the entire tree is displayed.
The format of a node identifier is entityType:entityReference, where the entity type can be wiki, space or page. E.g.: wiki:xwiki, space:xwiki:Main, document:xwiki:Main.WebHome
If you use an Entity Type other than document, you must also set the show[entity_type] parameter to true.
None
showAttachmentsYesWhether to display the page attachments or not.true
showChildDocumentsYes

Whether to display the child pages based on the page parent field or not.
This parameter is deprecated since version 7.2 so you should use hierarchyMode instead.
Also, child pages are now sorted by their raw translated title, with a fall-back on the raw default title and then on the page name.
Finally, child pages are sorted by their name when the showDocumentTitle parameter is set to false.

true
showClassPropertiesYesWhether to display the class properties for pages that hold class definitions or not.false
showDocumentTitleYes

Whether to show the page title instead of the page name when displaying a page node.
The tree now displays the rendered translated page title when this parameter is set to true.

true
showObjectsYesWhether to display the attached page objects or not.false
showOnlyViewableYesWhether to display only the wiki, space and page nodes for which the current user has view rights. In case this parameter is set to false, the user not having view rights will only see the node names.true
showRootYesWhether to show the root node or not. The root node is not displayed by default because it is usually implied from the context where the tree is displayed.false
showSpacesYesWhether to display the space nodes or not. If this parameter is set to true, the pages will be grouped by space.false
showTranslationsYesWhether to display page translations or not.true
showWikisYesWhether to show the wiki nodes or not. This parameter can be used only on the main wiki and only if the tree source has been saved with programming rights.false
showWikiPrettyNameYesWhether to display the wiki pretty name instead of the wiki domain name when showing a wiki node.true
The support for relative references in the root and openTo parameters has been improved, but you still need to prefix the entity reference with its entity type.

Starting with version 7.4, there is a dedicated Velocity macro available:

#set ($treeParams = {
     'limit': 10,
     'links': true,
     'hierarchyMode': 'parentchild',
     'showTranslations': true,
     'showSpaces': true
    })

#documentTree($treeParams)

Examples

1. Empty document tree:

EmptyDocumentTree.png

2. Nested document tree:

{{documentTree root="space:XWiki" showSpaces="true" showObjects="true" showClassProperties="true" showRoot="true"/}}

NestedDocumentTree.png

3. Compact tree with checkboxes:

{{documentTree compact='true' checkboxes='true'/}}

DocumentTreeMacro1.png

4. Parent-child document tree grouped by spaces: 

{{documentTree hierarchyMode='parentchild' showSpaces='true' /}}

DocumentTreeMacro2.png

5. Full entity tree: 

{{documentTree showWikis="true" showWikiPrettyName="false" showSpaces="true" showDocumentTitle="false"
showChildDocuments="false" showObjects="true" showClassProperties="true" /}}

DocumentTreeMacro3.png

   

Search this space