Skip to Content

Creating a Tree View

Version 1.2 by Marius Dumitru Florea on 2015/07/28
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.CreatingATreeView.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Agenda

Use case

Display the employee hierarchy within a company using a tree widget. Each employee has an associated XWiki user. In order to describe the hierarchy we have added two new properties to the XWiki.XWikiUsers xclass:

  • manager:String (identifies the manager of an user)
  • jobtitle:String (the position the user has inside the company)

For our use case the XWiki users are synchronized with LDAP so the user profile document has an object of type XWiki.LDAPProfileClass. The relation between an employee and its manager is defined by:

XWikiUsers.manager(Alice) == LDAPProfileClass.dn(Bob) => Bob is manager of Alice

Static Wiki Syntax Tree

The most easiest way to create a tree is by using the Tree Macro with wiki syntax.

{{tree}}
* [[Ludovic Dubost (CEO)>>XWiki.ldubost]]
** [[Vincent Massol (CTO)>>XWiki.vmassol]]
*** [[image:XWiki.mflorea@mflorea.jpg||width="24px"]] [[Marius Florea (R&D Engineer)>>XWiki.mflorea]]
** [[Silvia Rusu (Support & QA Manager)>>XWiki.srusu]]
*** [[Oana Tăbăranu (Support & Documentation Team Leader)>>XWiki.otabaranu]]
** [[Guillaume Lerouge (Sales & Marketing Director)>>XWiki.glerouge]]
{{/tree}}

The syntax is concise and the tree will degrade nicely when JavaScript is disabled, but unfortunately the links and the custom icons don't work. In the future, the tree could, as an improvement, modify the HTML produced by the wiki syntax to match the jsTree (the tree widget used under the hood) expectations, but it's not the case right now.

Static HTML Tree

We can fix the links and the node icons by using HTML:

{{tree}}
{{velocity}}
{{html}}
<ul>
  <li data-jstree='{"icon": "$xwiki.getDocument('XWiki.ldubost').getAttachmentURL('ludovic-dubost-2015v13-profile.jpg', 'download', 'width=24')"}'>
    <a href="$xwiki.getURL('XWiki.ldubost')">Ludovic Dubost (CEO)</a>
    <ul>
      <li data-jstree='{"icon": "$xwiki.getDocument('XWiki.vmassol').getAttachmentURL('vincent.png', 'download', 'width=24')"}'>
        <a href="$xwiki.getURL('XWiki.vmassol')">Vincent Massol (CTO)</a>
        <ul>
          <li data-jstree='{"icon": "$xwiki.getDocument('XWiki.mflorea').getAttachmentURL('mflorea.jpg', 'download', 'width=24')"}'>
            <a href="$xwiki.getURL('XWiki.mflorea')">Marius Florea (R&D Engineer)</a>
          </li>
        </ul>
      </li>
      <li>
        <a href="$xwiki.getURL('XWiki.srusu')">Silvia Rusu (Support & QA Manager)</a>
        <ul>
          <li>
            <a href="$xwiki.getURL('XWiki.otabaranu')">Oana Tăbăranu (Support & Documentation Team Leader)</a>
          </li>
        </ul>
      </li>
      <li>
        <a href="$xwiki.getURL('XWiki.glerouge')">Guillaume Lerouge (Sales & Marketing Director)</a>
      </li>
    </ul>
  </li>
</ul>
{{/html}}
{{/velocity}}
{{/tree}}

As you can see the syntax is more verbose and we also need to use a bit of:

  • Velocity, in order to compute the link/icon URLs
  • JSON, in order to specify the custom node icon

The tree still degrades nicely when JavaScript is disabled but the syntax mix is not appealing. See the HTML source documentation for more details.

Static JSON Tree

If you want to describe the tree structure in a more semantic way then you better use a JSON source.

{{tree reference="StaticJSONTreeSource" openTo="mflorea" /}}

The JSON source looks like this:

{{velocity wiki="false"}}
$response.setContentType('application/json')
$jsontool.serialize({
  'id': 'ldubost',
  'text': 'Ludovic Dubost (CEO)',
  'icon': $xwiki.getDocument('XWiki.ldubost').getAttachmentURL('ludovic-dubost-2015v13-profile.jpg', 'download', 'width=24'),
  'a_attr': {
    'href': $xwiki.getURL('XWiki.ldubost')
  },
  'children': [
    {
      'id': 'vmassol',
      'text': 'Vincent Massol (CTO)',
      'icon': $xwiki.getDocument('XWiki.vmassol').getAttachmentURL('vincent.png', 'download', 'width=24'),
      'a_attr': {
        'href': $xwiki.getURL('XWiki.vmassol')
      },
      'children': [
        {
          'id': 'mflorea',
          'text': 'Marius Florea (R&D Engineer)',
          'icon': $xwiki.getDocument('XWiki.mflorea').getAttachmentURL('mflorea.jpg', 'download', 'width=24'),
          'a_attr': {
            'href': $xwiki.getURL('XWiki.mflorea')
          }
        }
      ]
    },
    {
      'id': 'srusu',
      'text': 'Silvia Rusu (Support & QA Manager)',
      'a_attr': {
        'href': $xwiki.getURL('XWiki.srusu')
      },
      'children': [
        {
          'id': 'otabaranu',
          'text': 'Oana Tăbăranu (Support & Documentation Team Leader)',
          'a_attr': {
            'href': $xwiki.getURL('XWiki.otabaranu')
          }
        }
      ]
    },
    {
      'id': 'glerouge',
      'text': 'Guillaume Lerouge (Sales & Marketing Director)',
      'a_attr': {
        'href': $xwiki.getURL('XWiki.glerouge')
      }
    }
  ]
})
{{/velocity}}

Check the JSON data documentation for more details. We still need a bit of Velocity to compute the URLs and to set the content type to application/json. The source is defined in a different document this time. In the future we may add the ability to put JSON directly in the content of the Tree Macro (with a content type parameter) but for now you need a separate document.

One benefit of using the JSON source is that you can use parameters such as openTo (because we specify node ids in the JSON).

Note that the tree is no longer degrading nicely when JavaScript is disabled because it needs to make an AJAX request to retrieve the JSON. Moreover, the tree won't scale if it's big. The solution is to implement lazy loading.

Dynamic Team Hierarchy Tree v1 (lazy loading)

The key to implement lazy loading is the "children" property: instead of specifying the child nodes explicitly (in place) we can set it to:

  • false: meaning the node doesn't have child nodes
  • true: meaning the node has child nodes but the tree needs to make a separate request to get those child nodes
{{tree reference="TeamHierarchyTreeSourceV1" /}}
{{velocity output="false"}}
#macro (handleTeamHierarchyTreeRequest)
  #if ($request.data == 'children')
    #getChildren($request.id $data)
    $response.setContentType('application/json')
    $jsontool.serialize($data)
  #end
#end

#macro (getChildren $nodeId $return)
  #if ($nodeId == '#')
    ## Get the root nodes.
    #set ($userReference = $NULL)
  #else
    ## Get the child nodes of the specified parent node.
    #set ($userReference = $services.model.createDocumentReference('', 'XWiki', $nodeId))
  #end
  #getChildrenQuery($userReference $childrenQuery)
  #set ($children = [])
  #foreach ($userId in $childrenQuery.execute())
    #set ($userReference = $services.model.resolveDocument($userId))
    #addUserNode($userReference $children)
  #end
  #set ($return = $NULL)
  #setVariable("$return" $children)
#end

#macro (getChildrenQuery $userReference $return)
  #set ($dn = '')
  #if ($userReference)
    #set ($userDocument = $xwiki.getDocument($userReference))
    #set ($dn = $userDocument.getValue('dn'))
  #end
  #set ($query = $services.query.xwql("where doc.object(XWiki.XWikiUsers).manager = :manager"))
  #set ($query = $query.bindValue('manager', $dn))
  #set ($return = $NULL)
  #setVariable("$return" $query)
#end

#macro (addUserNode $userReference $siblings)
  #set ($userDocument = $xwiki.getDocument($userReference))
  #set ($jobTitle = $userDocument.getValue('jobtitle'))
  #set ($userName = $xwiki.getPlainUserName($userReference))
  #getUserAvatarURL($userReference $avatarURL 24)
  #getChildrenQuery($userReference $countQuery)
  #set ($hasChildren = $countQuery.count() > 0)
  #set ($discard = $siblings.add({
    'id': $userReference.name,
    'text': "$userName ($jobTitle)",
    'icon': $avatarURL.url,
    'children': $hasChildren,
    'a_attr': {
      'href': $xwiki.getURL($userReference)
    }
  }))
#end
{{/velocity}}

{{velocity wiki="false"}}
#if ($xcontext.action == 'get')
  #handleTeamHierarchyTreeRequest
#end
{{/velocity}}

As you can see the tree sends an AJAX request with ?data=children&id=<parentNodeId>:

  • when the tree is loading (id=#, because by convention # is the identifier of the tree root; in other words # is the parent of the top level nodes; the # node is not visible)
  • when a tree node is expanded for the fist time (id=expandedNodeId)

All we have to do is to write some Velocity code to get the child nodes of the specified parent node.

Let's see if the openTo parameter still works:

{{tree reference="TeamHierarchyTreeSourceV1" openTo="mflorea" /}}

It doesn't.. which is normal because now the tree is not fully loaded until you expand all the nodes. If we want to open the tree to a node that hasn't been added to the tree yet then we need to specify the node path somehow so that the tree can expand all the ancestors of that node.

Dynamic Team Hierarchy Tree v2 (open to)

{{tree reference="TeamHierarchyTreeSourceV2" openTo="mflorea" /}}

When the tree doesn't find a specified node it sends a new AJAX request to retrieve the path of that node so that it can load the ancestors nodes before the node itself.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.CreatingATreeView.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Dynamic Team Hierarchy Tree v3 (finder)

Next step is to implement a finder for our tree. The idea is to display a text input above the tree that provides suggestions as you type. When a suggestion is selected the tree is opened up to the associated node.

{{tree reference="TeamHierarchyTreeSourceV2" finder="true" /}}

For this we need to handle the ?data=suggestions request sent by the tree when the user types in the finder text input.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.CreatingATreeView.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

As you can see we're using Solr to retrieve the suggestions.

Dynamic Team Hierarchy Tree v1 (context menu)

The tree looks good but we cannot perform any action on the tree nodes. Let's start by adding a context menu that will expose some of the actions.

{{tree reference="TeamHierarchyTreeSourceV3" finder="true" contextMenu="true" /}}

This time we need to handle the ?data=contextMenu request.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.CreatingATreeView.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

We made 3 important changes:

  1. We started handling the ?action=* requests, although for the moment we just return "The specified action is not supported."
  2. We're handling the ?data=contextMenu request. As you can see the context menu is described using JSON.
  3. We added more data to the node JSON. This is needed because the tree supports actions only on the nodes that have an associated entity. Note that the additional node data can be used to restrict some actions based on the access rights of the current user.

Dynamic Team Hierarchy Tree v1 (drag & drop)

The final step is to implement the actions. We'll show how to implement move using drag & drop.

{{tree reference="TeamHierarchyTreeSourceV3" finder="true" contextMenu="true" dragAndDrop="true" /}}

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.CreatingATreeView.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

As you can see we need to handle the ?action=move request. Note that we had to add more meta data to the node JSON. When performing drag & drop the tree needs to know whether the new parent is allowed to have the new child node. We use the type and validChildren properties for this. You can also restrict the move action based on the access rights of the current use, by using the canMove property.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected