ARIA Trees

Expected behaviors

Ensure that each tree has only one tab stop and that available tree items can be navigated using the arrow keys in the same manner as a native Windows TreeView control.

The 4X ARIA Tree module automatically configures all required ARIA attributes and focus handling, in strict accordance with the ARIA specification.

The following attributes are handled automatically by the Tree module:

  • role=tree
  • role=group
  • role=treeitem
  • aria-expanded
  • aria-checked
  • aria-owns
  • aria-level
  • aria-multiselectable
  • aria-selected
  • tabindex

Available attributes for tree item links:

  • data-controls : The resource path and pointer to the ID attribute of the subtree container element.
  • data-check : May be set to "false", "true", or "mixed" to set the current state of a checkbox tree item when rendered.

HTML syntax

Standard Tree

<ul class="aria-tree top">
  <li>
    <a>
      Name One
    </a>

    <ul>
      <li>
        <a>
          Name Two
        </a>
      </li>
    </ul>

  </li>
</ul>

Standard Tree Including Checkable Items

<ul class="aria-tree top">
  <li>
    <a>
      Name One
    </a>

    <ul>
      <li>
        <a data-check >
          Name Two
        </a>
      </li>
    </ul>

  </li>
</ul>

IMPORTANT: An ARIA Tree must never include any other active elements other than those specified as tree items. Otherwise, all such additional active elements will be undiscoverable and inaccessible to non-sighted screen reader users.

Whenever a hidden checkbox is embedded within a checkable tree item element, it will automatically reflect the toggled state of the parent element. This makes it possible to implement custom toggle controls that can be submitted in the same manner as native form controls. This, however, is optional, and may be removed without having any negative impact on the functionality of the simulated toggle control.

JavaScript syntax

var myTreeDC = $A.setTree( DOMNodeOrCSSSelectorForRootContainer, {
// Configure functionality key / value mappings
});

Parameters

  1. A DOM element or CSS selector to specify the top level container element of the tree structure
  2. A configuration map to customize behaviors and options

If there is no tree structure to reference, the configuration map can be passed as the first parameter.

Configuration

{

// Optionally specify the content to be rendered when referencing external content.
// If set, the content property will be auto-populated with the returned content.
fetch: {
url: "path/file.htm",
data: {
selector: "#uniqueId"
}
},

// Optionally specify a DOM node where the tree will be inserted within.
// Only applicable when fetching an external tree structure to render.
root: undefined,

// Optionally toggle the hidden attribute instead of inserting the tree content when rendered.
    toggleHide: true,

// Preload markup in the background when using the Fetch API to load external content.
preload: true,

// Preload images in the background when using the Fetch API to load external content.
preloadImages: true,

tag: {

// CSS selector for the top level tree container.
parent: "ul",

// The CSS selector that identifies the focusable active element within each child tag markup.
// Only one focusable element is allowed within each child tag.
// If the child tag markup is changed, this selector must also be changed to point to the focusable active element within that markup.
child: "a",

// Return an array of all focusable child elements within the tree container element.
parse: function(ref) {
if ($A.isIE()) {
var mItems = [];
$A.query(ref.children, function(i, o) {
var c = $A.first(o, function(e) {
if (e.nodeName.toLowerCase() === "a")
return true;
});
if ($A.isNode(c)) mItems.push(c);
});
return mItems;
} else
return ref.querySelectorAll(":scope > * > a");
}

},

// Set a custom event handler to process every time a tree item is activated.
onActivate: function(event, triggerNode, RTI, boundElement, currentState, set) {
// If the tree item is checkable, currentState will include a number from 0 to 2.
// (0 = "false", 1 = "true", 2 = "mixed".)
// The set function can be used to set a new state for the option.
// E.G. set("false"), set("true"), or set("mixed") for checkbox tree items only.
},

// Optionally run a script after the tree finishes rendering.
afterRender: function(DC) {
// DC.container includes the rendered tree content.
},

// Optionally run a script after the tree is removed.
afterRemove: function(DC) {
// Do something.
},

// Optionally specify a render and remove animation effect for the tree.
// Requires the "Animate" module import to function, which is powered by Velocity.js.
// To ignore animation effects, delete the animate object declaration entirely from the setup script.
// View implementations within "Templates/Trees" for practical animation usage examples.

style: { display: "none" }, // Set the initial state to hidden in prep for animation.

animate: {

onRender: function(dc, wrapper, next) {

// Specify the render animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for rendering.
}
});

},

onRemove: function(dc, wrapper, next) {

// Specify the removal animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for removal.
}
});

}

},

// Optionally extend the RTI instance with custom event handlers.
// For available options, view the RovingTabIndex help doc at "Help/Module Imports/Actions/RovingTabIndex".
extendRTI: {
// Optional event handlers.
}

// Additional DC API properties and methods can be declared here also to customize functionality and behavior.
// To view available options, reference the help docs located at: "Help/DC API/DC Object Configuration"

}