Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.InplaceEditing]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.InplaceEditing]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:SyntaxHighlighting.EnableSyntaxHighlighting]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:CKEditor.EditMenuEntry]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.AvailableTemplateProvidersFilter]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Ratings.RatingsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Ratings.RatingsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Document Tree Macro

Version 51.16 by Admin on 2018/04/23 17:30
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.MissingLicensesUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.MissingLicensesUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
chart_organisationMacro used to display a hierarchy of XWiki documents by using a tree.
TypeXAR
CategoryMacro
Developed by

XWiki Development Team

Rating
2 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Standard

Compatibility

6.3RC1+

Installable with the Extension Manager

  Download v10.3SourcesIssues

Table of contents

Description

Displays a hierarchy of documents (or any other entities such as spaces, wikis, objects, etc) using the Tree Macro.

This macro is part of the Index Application, but since XWiki 7.3M2 it can also be used independently.

Usage

WYSIWYG Editor

You can insert this macro from the WYSIWYG Editor. Look for "Page Tree" in the list of macros.

editDocumentTreeMacroDialog.png

Wiki Macro

{{documentTree /}}

Velocity Macro

Starting with 7.4M1 there is also a Velocity macro available.

#documentTree({
  '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:

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

{{velocity}}
{{html}}
#documentTree({})
{{/html}}
{{/velocity}}

Parameters

NameDescriptionDefault ValueSince
checkboxesWhether to display a checkbox in front of each tree node to allow the user to select multiple tree nodes.false6.3RC1
compactIf 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.false6.3RC1
filterByClassShow 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. This parameter currently works only with hierarchyMode=parentchild.None6.4M1
filterHiddenDocumentsSet 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.true7.4M1
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
hierarchyModeSpecifies 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.reference7.2M2
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. 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.158.1M2
linksSpecifies whether the node labels should look and behave as links (anchors).true6.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. The format of the node id is the one used for the root parameter. Example: document:wiki:space1.space2.pageNone6.4M1
readOnlyShould 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.true6.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. The format of a node identifier is entityType:entityReference, 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=trueNone6.3RC1
showAttachmentsWhether to show the document attachments or not.true6.3RC1
showChildDocumentsWhether to show the child documents based on the document parent field. Deprecated since 7.2M2. Use the hierarchyMode parameter instead.true6.3RC1
showClassPropertiesWhether to show the class properties for documents that define classes.false6.3RC1
showDocumentTitleWhether 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.true6.3RC1
showObjectsWhether to show the document objects or not.false6.3RC1
showOnlyViewableShow 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).true6.4M1
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
showSpacesWhether to show the space nodes or not. The documents are grouped by space if the space nodes are displayed.false6.3RC1
showTranslationsWhether to show the document translations or not.true6.3RC1
showWikisWhether 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.false6.3RC1
showWikiPrettyNameShow the wiki pretty name instead of the wiki id when displaying a wiki node.true6.3RC1

Examples

Empty Document Tree

When the tree is empty the following message is displayed:

emptyDocTree.png

Children Pages

Displays children pages of the current page:

{{velocity}}
{{documentTree root="document:$doc.documentReference" /}}
{{/velocity}}

Nested Document Tree

This is the same tree you get in the Document Index Tree View since XWiki 7.2M2.

{{documentTree /}}

nestedDocTree.png

Nested Space Tree

{{documentTree showSpaces="true" /}}

nestedSpaceTree.png

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).

{{documentTree hierarchyMode="parentchild" /}}

parentChildTree.png

Parent-Child Mixed With Space Grouping

This is the same tree you get in the Document Index Tree View prior to XWiki 7.2M2.

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

spaceParentChildTree.png

Navigation Panel

{{documentTree showTranslations="false" showAttachments="false" compact="true" /}}

navigationPanel.png

Full Entity Tree

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

entityTree.png

Subtree with Checkboxes

{{documentTree root="document:xwiki:Sandbox.WebHome" checkboxes="true"/}}

subTreeWithCheckboxes.png

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:

{{tree reference="Path.To.MyCustomTreeDefinition" /}}

Check the following examples of custom tree definitions.

Exclude nodes based on their ids

{{include reference="XWiki.DocumentTreeMacros" /}}

{{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}}

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

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

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Like.LikeUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.PageTagsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
    

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected