Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Tree

From MoodleDocs

Moodle 3.1 The javascript Tree is designed to allow you to create an interactive tree that is accessible, intuitively usable, and consistent with the rest of Moodle's hierarchical interfaces. It is currently used in the Navigation block and Settings block.

The tree is originally based off the tree view example by the Open Ajax Alliance Accessibility Group. and is designed to comply as much as possible with the ARIA specification for accessible trees. For detailed additional information you can read those links.

An example use of the tree module

Using the Tree module

The following is a minimal example.

To create an aria accessible tree, you must instantiate a child AMD module of the core/tree using Require JS.

define(['jquery', 'core/tree'], function($, Tree) {
    return {
        init: function() {
            new Tree("#mytree"); // css/jquery selector of the tree container
        }
    };
});

To define a node in your structure, add the "treeitem" role. If the node has children, it must have a child html element with the role "group" to contain it's children. The example shows divs but this is not required; the tree could be constructed with (e.g.) lists if required.

<div role="tree" id="mytree">
    <div role="treeitem" aria-expanded="false">This is an item which has children
        <div role="group">
            <div role="treeitem">A child</div>
            <div role="treeitem">Another child</div>
        </div>
    </div>
<div>

tree.js does not perform the collapse/expand functionality nor does it add (for example) the appropriate indenting or collapse/expand icons. You must supply appropriate markup and CSS to achieve your requirements. You don't have to use divs, a nested list structure will work just as well. You will need to target the aria-expanded attribute of group items to hide and show them. For most cases, this will be sufficient:

[aria-expanded="false"] > [role="group"] {
    display: none;
}

Tree.js will handle the accessible controls for navigating the tree as well as expanding and collapsing nodes. The controls are as follows:

  • Up: Select the previous visible tree item.
  • Down: Select next visible tree item.
  • Left: Collapse the currently selected parent node if it is expanded. Move to the previous parent node (if possible) when the current parent node is collapsed.
  • Right: Expand the currently selected parent node and move to the first child list item.
  • Enter: Toggle the expanded or collapsed state of the selected parent node. If it is a link, follow the link
  • Home: Select the root parent node of the tree.
  • End: Select the last visible node of the tree.
  • Tab: Navigate away from tree.
  • Space: Expand and collapse node
  • * (asterisk on the numpad): Expand all group nodes.
  • Clicking on a parent node will toggle its expanded or collapsed state.

It is possible (from Moodle 3.10) to override the above behaviour for activation keys (enter and space), by adding the 'data-overrides-tree-activation-key-handler' attribute to a tree node. This will prevent Tree.js from triggering its usual callback/redirect behaviour, and instead trigger any custom handler on the node.

Code

  • Code location: lib/amd/src/tree.js
  • Examples:
    • blocks/navigation/amd/src/navblock.js
    • blocks/settings/amd/src/settingsblock.js

See also