"documentTree" Macro
Reference
Description
The documentTree macro displays the pages of the wiki as a tree that the reader expands node by node. Depending on its parameters, the tree also shows wikis, spaces, attachments, translations, objects and class properties.
It is the tree of the Page Index. To list only the children of the current page, the "children" macro is a shorter way to write it.
Usage
{{documentTree/}}In the WYSIWYG editor the macro is listed as "Page Tree", in the Navigation category. Its parameters are spread over four tabs: "Optional parameters", "Filters", "Elements to show" and "Display options".
The macro is standalone only and takes no content. A tree with nothing to show displays the message "No pages found".
Node Identifiers
The root, openTo and exclusions parameters designate nodes of the tree. A node id is written type:reference. In the Edit Macro dialog, the "Root" and "Open to" fields are node pickers: a button selects the type and the field next to it takes the reference, with suggestions for pages and attachments.
| Type in the Picker | Node Id | Reference to Give |
|---|---|---|
| Farm | farm:* | None: leave the field empty in the picker. |
| Wiki | wiki:xwiki | The name of the wiki. |
| Space | space:xwiki:Sandbox | The reference of the space. For the page xwiki:Sandbox.WebHome it is xwiki:Sandbox. |
| Document | document:xwiki:Sandbox.WebHome | The reference of the page. See how to get the reference of a page. document: alone is the current page. |
| All attachments | attachments:xwiki:Sandbox.WebHome | The reference of the page holding the attachments. |
| Attachment | attachment:xwiki:[email protected] | The reference of the attachment. |
| All translations | translations:xwiki:Sandbox.WebHome | The reference of the translated page. |
| All objects | objects:xwiki:Sandbox.WebHome | The reference of the page holding the objects. |
| Objects of type | objectsOfType:xwiki:Main.WebHome^XWiki.StyleSheetExtension | The reference of the page, then ^ and the reference of the class. The picker offers no suggestion for this type. |
A node is only reachable when the tree shows its type: a space: root needs showSpaces="true", an objects: root needs showObjects="true", and so on. Otherwise the tree displays "No pages found".
Velocity Macro
The same tree is available to scripts as the #documentTree Velocity macro of the documentTree_macros.vm template. It takes the same parameters as a map, except for exclusions, which expects a set of node ids instead of a comma-separated list.
{{template name="documentTree_macros.vm"/}}
{{velocity}}
{{html}}
#documentTree({'showAttachments': false, 'exclusions': $collectiontool.set})
{{/html}}
{{/velocity}}Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| root | no | a node id | none | The node whose descendants are displayed. The root itself is not part of the tree unless showRoot is set. Without a root the tree displays the whole wiki. |
| openTo | no | a node id | none | The node to open the tree to. All its ancestors, up to the root of the tree, are opened as well. |
| limit | no | a positive integer | 15 | The maximum number of child nodes displayed when a node is expanded for the first time. The others are reached through a "more ..." link. When a single child is left over, it is displayed instead of the link. |
| sortDocumentsBy | no | title, name, date for the last modification date or creationDate, optionally followed by :asc or :desc | title:asc when showDocumentTitle is true, name:asc otherwise | The page field used to sort the child pages, and the sort order. The order is ascending when it is left out. The "Sort pages by" field of the Edit Macro dialog does not offer name: sorting on the page name is only available in wiki syntax. Sorting by title uses the raw title, so pages whose title is computed by a script may not be at the expected place. |
| readOnly | no | true, false | true | Set it to false to let users who have the necessary rights change the tree structure, with drag and drop and a context menu on the nodes. |
| hierarchyMode | no | reference, parentchild | reference | The hierarchy the tree follows. With reference, a page is under the page its reference is nested in. With parentchild, a page is under the page set as its parent, wherever it is located. This parameter is listed as advanced in the Edit Macro dialog. |
| exclusions | no | a comma-separated list of node ids | none | The nodes to leave out of the tree, for instance exclusions="wiki:dev,document:xwiki:Sandbox.WebHome". It only applies when hierarchyMode is reference, and only to wiki and page nodes. |
| filterByClass | no | the reference of a page holding a class, such as Blog.CategoryClass | none | Show only the pages that have an object of this class. It only applies when hierarchyMode is parentchild. |
| filterHiddenDocuments | no | true, false | true | When true, hidden pages are displayed or not according to the preference of the reader. Set it to false to always display them. |
| showAttachments | no | true, false | true | Whether to show the attachments of each page, in an "Attachments" node. |
| showClassProperties | no | true, false | false | Whether to show the class properties of the pages that define a class. |
| showDocumentTitle | no | true, false | true | Whether a page node displays the title of the page, in the language of the reader, instead of its name. |
| showObjects | no | true, false | false | Whether to show the objects of each page. |
| showOnlyViewable | no | true, false | true | Show only the wikis, spaces and pages the reader is allowed to view. When false, the others are listed by their name: the reader learns that they exist but still cannot open them. |
| showRoot | no | true, false | false | Whether to display the root node itself, above its children. |
| showSpaces | no | true, false | false | Whether to show the space nodes. The pages are then grouped by space. |
| showTranslations | no | true, false | true | Whether to show the translations of each page, in a "Translations" node. |
| showWikiPrettyName | no | true, false | true | Whether a wiki node displays the pretty name of the wiki instead of its identifier. |
| showWikis | no | true, false | false | Whether to show the wiki nodes. It only works on the main wiki, and when the page calling the macro was saved by a user with programming rights. |
| checkboxes | no | true, false | false | Whether to display a checkbox in front of each node, to let the reader select several nodes. |
| compact | no | true, false | false | Hide the node icons and the lines connecting the nodes, so that the tree takes less horizontal space. Meant for narrow places such as a panel. |
| expandToLevel | no | a positive integer or 0 | 0 | The number of levels opened when the tree is displayed. With 0 only the top level nodes are displayed, 1 opens them, 2 also opens their children, and so on. A high value makes the tree slow to display. |
| finder | no | true, false | false | Whether to display a search field above the tree. It suggests nodes as the reader types and opens the tree to the selected one. |
| links | no | true, false | true | Whether the node labels are links. |
Examples
Display the Pages of the Wiki
{{documentTree/}}Display the Pages Below a Page
The tree starts under the Team page and is opened one level deep. The Guides page has an attachment, hence its Attachments node.
{{documentTree root="document:xwiki:Sandbox.TreeShots.Team.WebHome" expandToLevel="1"/}}
Display a Compact Tree of Pages Only
This is the form to use in a panel: no attachment, no translation, no icon.
{{documentTree root="document:xwiki:Sandbox.TreeShots.Team.WebHome" expandToLevel="1" showAttachments="false" showTranslations="false" compact="true"/}}
Display the Root with Checkboxes and a Finder
{{documentTree root="document:xwiki:Sandbox.TreeShots.Team.WebHome" showRoot="true" checkboxes="true" finder="true"/}}
Group the Pages by Space
{{documentTree showSpaces="true"/}}Follow the Parent of Each Page
The tree follows the parent set on each page instead of the page location. Add showSpaces="true" to also group the pages by space.
{{documentTree hierarchyMode="parentchild"/}}Display Every Kind of Node
{{documentTree showWikis="true" showWikiPrettyName="false" showSpaces="true" showDocumentTitle="false" showObjects="true" showClassProperties="true"/}}
