A tree widget based on jsTree

Description

 The tree widget is based on jsTree and thus it provides all the features supported by jsTree plus a few extra. You can create both static and dynamic (interactive) trees where the tree structure and behaviour is defined in a wiki page. It is written as a jQuery plugin that extends the jsTree plugin adding a few extra APIs to ease the integration with XWiki.

Usage

Maven Dependency

In order to use the tree widget in your extension the first step would probably be to add the tree widget as a dependency.

Of course, you can change the version. Note that the tree widget is packaged as a WebJar so you should also add a dependency to the WebJar integration module.

RequireJS Configuration

Next, you need to load the tree widget. The recommended way is through RequireJS. Here's an example configuration:

Then you can create a tree:

The difference from creating the tree with jsTree is that you have to call 'xtree' instead of 'jstree' but otherwise it will behave the same. As with jsTree, you can pass a configuration object. You can put this code (including the RequireJS configuration) in a JavaScriptExtension object for instance. 

Besides the JavaScript code, you also have to load the CSS. You can obtain the URL like this:

Note that the CSS is evaluated because it uses Color Theme variables (i.e. Velocity code). You can load the CSS statically, or dynamically with a bit of JavaScript help:

Configuration

From JavaScript

When you create a tree you can pass a configuration object:

See the jsTree documentation for all the available options.

From HTML

You can also configure the tree from the HTML using 'data' attributes:

You can also use a special CSS class 'jstree-no-links' to disable default link behaviour (i.e. clicking on a node will select the node instead of following the link). You can set this CSS class on the tree element to affect the entire tree or on a tree node element to affect that node and its descendants. If you want to disable the default link behaviour for a specific tree node without affecting its child nodes then you can use the 'jstree-no-link' CSS class instead (7.4M2+), which can also be set from JSON, as shown in the Advanced Node Data section below.

API

In order to get a reference to the tree object you can use the standard jsTree API:

Then you can call any method provided by jsTree and a few more extra:

• Open the tree to a specified node, that is not necessarily loaded:
  tree.openTo('someNodeId', function(node) {
    console.log('done!');
  });

  The tree will ask the server side for the node path and it will open all the ancestors of the specified node. If the tree is paginated and one of the ancestors is not on the first 'page' of its parent (when the parent is expanded) then the ancestor will be added to the parent (since loading all the 'pages' would be too expensive). This doesn't affect the pagination, as when the 'page' that actually contains the ancestor is retrieved, the ancestor won't be added again to the tree.

  If you don't pass any callback function (as the second parameter) then the tree will select the specified node. Otherwise, if you pass a callback function, you'll have to select the node yourself (in the callback) if you wish to. Note that the node passed to the callback function is the last node from the path that could be opened. So this is not necessarily the node you wanted. You can check its id if you want to make sure.

• Refresh a node:
  tree.refreshNode('someNodeId');

  The difference from jsTree's 'refresh_node' is that this also works for the root node.

• Execute an action on a node:
  var targetNode = tree.get_node('nodeId');
  var actionName = 'pack';
  var actionParams = {
   'format': 'xar'
  };
  var promise = tree.execute(actionName, targetNode, actionParams);

  This will call the server side specifying the target node, the action to execute and its parameters. You can use the returned promise to get notified of the progress. Note that the server side can even perform the action using (asynchronous) jobs. The returned promise will behave as expected as long as the server side returns the job status (partially) serialized as JSON.

Events

The events are triggered on the tree element so you can use jQuery listen to them like this:

Besides the standard jsTree events, the following events are specific to the tree widget:

Tree Data

Static Data

Static trees can be defined using nested unordered lists inside the target HTML element:

See the jsTree's HTML data source for more information.

Dynamic Data

Dynamic tree data is loaded using the url data attribute.

The resource behind the specified URL must implement the following API (contract):

• Request some data

  • ?data=children&id=<parentNodeId>&offset=<offset>&showRoot=<true|false>&root=<rootNodeId>

    Requests the children of the specified parent node from the specified offset. The resource decides how many child nodes to return. The resource is expected to implement the following behaviour:

    • if id equals '#' then the top level nodes in the tree are requested (i.e. the first level in the tree)
      • if showRoot=true then return information about the specified root node or about the default root node in your tree model
      • else return information about the children of the specified root node or the children of the default root node in your tree model
    • else return information about the children of the specified tree node

    The response is a JSON array with node data. See jsTree's JSON data source for more information.

  • ?data=path&id=<nodeId>&root=<rootNodeId>

    Requests the path of the specified node. The response is a JSON array that contains data about all the ancestors of the specified node (including itself) starting from the specified root node or from the default root node in your tree model. The response is similar to the one returned when the list of child nodes is requested, only that this time the list of ancestors is returned.

  • ?data=contextmenu

    Requests the tree context menu. The response is a JSON object (map) where the key is the node type and the value is the context menu for that node type. See jsTree's context menu definition for more information.

  • ?data=jobStatus&id=<jobId>

    Requests the status for the specified job. This is needed when a tree action is performed using asynchronous jobs. The response is a JSON object that looks like this:

    {
     'id': $jobId,
     'state': $jobStatus.state,
     'request': {
       'type': $jobStatus.request.getProperty('job.type'),
       'user': "$jobStatus.request.getProperty('user.reference')"
      },
     'progress': {
       'offset': $jobStatus.progress.offset,
       'currentLevelOffset': $jobStatus.progress.currentLevelOffset
      },
     'startDate': $jobStatus.startDate,
     'endDate': $jobStatus.endDate
    }

    As you can notice the response is a partial serialization of the job status. You can add more data depending on the performed action, of course.

• Request an action: ?action=<actionName>. The action can be performed both synchronous and asynchronous. For synchronous actions it's enough to return the proper HTTP status code for success and failure. For asynchronous actions (e.g. a job running in background in a separate thread) you may want to return the job status as JSON.

If you want to create your own dynamic tree then follow the Creating a Tree View tutorial. For advanced examples of dynamic trees please checkout:

• the Document Tree
• the File Manager Tree

Advanced Node Data

Besides what is supported by jsTree's JSON format for node data, the tree widget also supports this:

If drag&drop is enabled then the tree widget will prevent moving nodes in the wrong place based on the node type and its valid children. The can* properties are used to enable/disable standard operations on tree nodes. The custom action URL can be used for standard actions (e.g. delete, move, copy) but also for custom actions (from the context menu).

Starting with XWiki 7.4M2 you can also disable the default link behaviour for a specific tree node without affecting its children, by using the 'jstree-no-link' CSS class like this:

Pagination

The tree widget supports a special node type 'pagination':

When the pagination node is clicked the tree makes a request to get the children of the pagination parent node, from the specified offset, and replaces the pagination node with the response. Obviously the response can contain another pagination node that will be used to get the next 'page'. The pagination node is usually the last child in the response.

Context Menu

jsTree provides support for creating context menus but you need to specify the menu structure on the client side. The tree widget adds support for retrieving the context menu structure from the server in JSON format. Since you cannot pass a function in JSON you need to specify the menu actions (what happens when a menu is clicked) a bit differently.

If you have a menu like this in jsTree:

this is how you would write it for the tree widget:

If the action name is the same as the menu item id (key) then you can omit the action name as in:

Note that menu actions can have parameters so you can write something like this:

Note that this way you can have multiple menu items that reuse the same action, but with different parameters.

Default menu items

The following menu items are provided by default:

Finder

Starting with version 6.4.1 the tree widget has a (jsTree) plugin to find tree nodes, called finder. When enabled, this plugin adds a text input above the tree that offers suggestions as you type based on the content of the tree. When such a suggestion is selected the tree is expanded to show the corresponding node.

You enable and configure the finder plugin like any other jsTree plugin:

Examples

The tree widget is currently used by:

• File Manager Application
• Tree Macro
• Document Tree Macro
• Navigation Panel
• The WYSIWYG Editor

Static Tree

Create a new page Test.StaticTree with the following content:

Then add a JavaScriptObject with this content to the same page:

Make sure you set the "Parse content" property to Yes, then save and view the page. Check the jsTree documentation for more configuration options.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-tree-webjar 16.10.1):

• org.webjars:requirejs 2.3.7
• org.webjars:jquery 3.7.1
• org.webjars:jstree 3.3.16
• org.xwiki.platform:xwiki-platform-job-webjar 16.10.1
• org.xwiki.platform:xwiki-platform-webjars-api 16.10.1