Document Picker

Last modified by Marius Dumitru Florea on 2015/09/16 13:28

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 Enterprise




This API is unstable and may suffer changes in the next versions.

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': ''
Created by Marius Dumitru Florea on 2015/09/16 11:59

Get Connected