Tree: Difference between revisions
John Okely (talk | contribs) (Document lib/amd/src/tree.js) |
David Mudrak (talk | contribs) m (Text replacement - "<code (.*)>" to "<syntaxhighlight lang="$1">") |
||
(14 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 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. | {{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 [http://oaa-accessibility.org/examplep/treeview1/ tree view example] by the Open Ajax Alliance Accessibility Group. and is designed to comply as much as possible with the [http://www.w3.org/WAI/GL/wiki/Using_ARIA_trees ARIA specification for accessible trees]. For detailed additional information you can read those links. | The tree is originally based off the [http://oaa-accessibility.org/examplep/treeview1/ tree view example] by the Open Ajax Alliance Accessibility Group. and is designed to comply as much as possible with the [http://www.w3.org/WAI/GL/wiki/Using_ARIA_trees ARIA specification for accessible trees]. For detailed additional information you can read those links. | ||
[[File:TreeExampleNavigation.png|thumb|center|450px|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. | To create an aria accessible tree, you must instantiate a child AMD module of the core/tree using Require JS. | ||
< | <syntaxhighlight lang="javascript"> | ||
define(['jquery', 'core/tree'], function($, Tree) { | |||
return { | |||
init: function() { | |||
new Tree("css/jquery selector of the tree container | new Tree("#mytree"); // css/jquery selector of the tree container | ||
} | } | ||
}; | |||
}); | |||
</ | </syntaxhighlight> | ||
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. | 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. | ||
< | <syntaxhighlight lang="xml"> | ||
<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> | |||
</syntaxhighlight> | |||
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: | |||
< | <syntaxhighlight lang="css"> | ||
[aria-expanded="false"] > [role="group"] { | |||
display: none; | |||
} | |||
</syntaxhighlight> | |||
</ | |||
Tree.js will handle the accessible controls for navigating the tree as well as expanding and collapsing nodes. The controls are as follows: | 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 == | |||
* [[Javascript Modules]] | |||
* [[Useful core Javascript modules]] | |||
* | |||
[[Category:Javascript]] | |||
Latest revision as of 08:19, 15 July 2021
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.
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