Document Picker

Last modified by slauriere on 2022/02/21 10:20

sitemap_colorSelect a document from a tree picker
TypeDoc (Velocity Macro)
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard




Provides a couple of Velocity macros and a widget to select a document from a tree picker and to display the path to the selected document.

Hierarchy Macro

The hierarchy Velocity macro is used to display the selected document. It can actually be used with any type of entity not just documents. The output is the path to the specified entity in the hierarchy. This macro is also used by the page breadcrumbs which are visible at the top of the page, above the page title.


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

#hierarchy($entityReference $options)

The definition of this macro is currently located in hierarchy_macros.vm so we need to include it. This may change in the future. The macro generates HTML so we need to wrap it in the HTML macro.


The macro accepts 2 parameters, both optional:

  • $entityReference specifies the entity for which to show the path in the hierarchy. If not specified, the macro displays the path to the current document.
  • $options is a map of (key, value) pairs of configuration options that control how the path is displayed.
    OptionDescriptionDefault ValueSince
    entitiesA map of (reference, entity) pairs holding unsaved entities that should be used for display instead of the corresponding entities from the database.[]7.2RC1
    excludeSelfWhether to exclude the passed reference from the path.false7.2RC1
    idThe value of the id attribute to set on the container element (when the output is HTML).None7.2RC1
    limitThe maximum number of path elements (limit/2 on the left and the rest of the right).07.2RC1
    localWhether to compute the local path or not (i.e. including the wiki reference or not).false7.2RC1
    plainWhether to output plain text or HTML.false7.2RC1


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

#set ($serializedReference = 'library:Books.Franz Kafka.Die [email protected]')
#set ($attachmentReference = $services.model.resolveAttachment($serializedReference))

The output should be similar to:


If you limit the path like this:

#hierarchy($attachmentReference {'limit': 4})

then the output becomes:


The plain path looks like this:

#hierarchy($attachmentReference {'plain': true})

Home / Library / Books / Franz Kafka / Die Verwandlung / cover.png

Location Picker Macro

The location picker Velocity macro is used to select a document that should be the target of some operation (e.g. copy, rename).


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

#set ($documentReference = $services.model.resolveDocument('Books.Franz Kafka.Die Verwandlung'))
#set ($selectedDocument = $xwiki.getDocument($documentReference))
<form class="xform" action="">
    'id': 'target',
    'title': {
      'label': 'core.create.title',
      'hint': 'core.create.title.hint',
      'name': 'title',
      'value': $selectedDocument.plainTitle,
      'placeholder': ''
    'preview': {
      'label': 'core.create.locationPreview.label',
      'hint': 'core.create.locationPreview.hint'
    'parent': {
      'label': 'core.create.spaceReference.label',
      'hint': 'core.create.spaceReference.hint',
      'name': 'spaceReference',
      'reference': $documentReference.parent,
      'placeholder': 'core.create.spaceReference.placeholder'
    'name': {
      'label': '',
      'hint': '',
      'name': 'name',
      'value': $,
      'placeholder': ''



NameDescriptionDefault valueSince
showTerminalDocuments When 'true', the terminal documents are displayed in the tree. Otherwise, the terminal documents are hidden.false
exclusionsList of nodes to exclude from the tree, specified by their id and separated by comma. Same parameter as in the Document Tree Macro.None14.1RC1

Get Connected