apex4x

<!doctype html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>ARIA Menus - Apex 4X Technical Style Guide</title> <meta name="description" content="Scalable ARIA Components" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link rel="stylesheet" type="text/css" href="../_common/_doc_files/css/global.css" /> <link rel="stylesheet" type="text/css" href="../_common/_doc_files/prism.css" /> <link rel="stylesheet" type="text/css" href="../_common/_doc_files/css/components-style.css" /> <script src="../_common/_doc_files/prism.js"></script> </head> <body> <div class="outer-wrapper"> <header class="header"> <div class="logo"> <a href="https://whatsock.com"> <img alt="WhatSock : Changing the world one step at a time" src="/Templates/_common/_doc_files/img/whatsock.svg" /> </a> </div> </header> <div class="wrapper"> <main id="main" class="main"> <h1><strong>ARIA Menus</strong></h1> <nav class="navigation--parent"> <p> <a href="/Tutorials/Beginner-Introduction.htm" >Beginner Tutorial</a > </p> <h2 class="parent--page">Template Examples</h2> <ul> <li><a href="../index.htm">Back to Components</a></li> <li><a href="External/index.htm">External</a></li> <li> <a href="External - Straylight/index.htm" >External - Straylight</a > </li> <li><a href="Internal/index.htm">Internal</a></li> <li> <a href="Internal - Straylight/index.htm" >Internal - Straylight</a > </li> <li> <a href="Simulated Textbox (Right-Click)/index.htm" >Simulated Textbox (Right-Click)</a > </li> </ul> </nav> <section class="section--instructions"> <h2>Expected behaviors</h2> <p> Move focus into the menu when it is rendered, ensure that each menu has only one tab stop and that available menu items can be navigated using the arrow keys, make sure the menu can be closed from the keyboard, and move focus back to the triggering element after the menu is removed. </p> <p> The 4X ARIA Menu module automatically configures all required ARIA attributes and focus handling, in strict accordance with the ARIA specification. </p> <p> The following attributes are handled automatically by the Menu module: </p> <ul> <li>role=menu</li> <li>role=menuitem/menuitemcheckbox/menuitemradio</li> <li>aria-checked</li> <li>aria-haspopup</li> <li>aria-orientation</li> <li>tabindex</li> </ul> <p>Available attributes for the triggering element:</p> <ul> <li> data-menu : The resource path and pointer to the ID attribute of the menu container element. </li> </ul> <p>Available attributes for menu item links:</p> <ul> <li> data-menu : The resource path and pointer to the ID attribute of the submenu container element. </li> <li> data-radio : May be set to "false" or "true" to set the current state of a radio menu item when rendered. </li> <li> data-check : May be set to "false", "true", or "mixed" to set the current state of a checkbox menu item when rendered. </li> </ul> <h2>HTML syntax</h2> <h3>Standard Menu</h3> <div> <pre><code class="language-markup"><ul id="menuId"> <li> <a href=" ... " > Accessible name and markup. </a> </li> </ul></code></pre> </div> <h3>Standard Menu Including Submenu</h3> <div> <pre><code class="language-markup"><ul id="menuId"> <li> <a href=" ... " > Accessible name and markup. </a> <ul> <li> <a href=" ... " > Accessible name and markup. </a> </li> </ul> </li> </ul></code></pre> </div> <h3>Standard Menu Including Checkable Items</h3> <div> <pre><code class="language-markup"><ul id="menuId"> <li> <a data-check="false" href=" ... " > Accessible name and markup. </a> </li> </ul></code></pre> </div> <h3>Standard Menu Including Checkable Radios</h3> <div> <pre><code class="language-markup"><ul id="menuId"> <li> <a data-radio href=" ... " > Accessible name and markup. </a> </li> <li> <a data-radio="true" href=" ... " > Accessible name and markup. </a> </li> </ul></code></pre> </div> <p> IMPORTANT: An ARIA Menu must never include any other active elements other than those specified as menu items. Otherwise, all such additional active elements will be undiscoverable and inaccessible to non-sighted screen reader users. </p> <h2>JavaScript syntax</h2> <div> <pre><code class="language-javascript">var myMenuDC = $A.setMenu( domNodeOrCSSSelectorForTriggeringElement , { // Configure functionality key / value mappings });</code></pre> </div> <ul> <li>Module file: Menu.js</li> <li>Requires: AccName.js, RovingTabIndex.js.</li> <li>Recommended: Velocity.js, VelocityUI.js.</li> </ul> <h2>Parameters</h2> <ol> <li> A DOM element or CSS selector to specify the triggering element </li> <li>A configuration map to customize behaviors and options</li> </ol> <h3 tabindex="-1" id="configure">Configuration</h3> <div> <pre><code class="language-javascript">{ // Optionally set a unique ID for the menu DC object, which can be referenced through $A('uniqueId') // If not specified, the id of the triggering element will be used instead. id: 'uniqueId', // Optionally specify the content to be rendered when referencing internal content. // May be a DOM node or CSS selector. // Not necessary if menu is set on the triggering element. content: "#uniqueId", // Specifies that the referenced content for rendering should not be dynamically inserted into the DOM, but will instead toggle the hidden attribute. toggleHide: true, // Optionally specify the content to be rendered when referencing external content. // Not necessary if menu is set on the triggering element. // If set, the content property will be auto-populated with the returned content. fetch: { url: "path/file.htm", data: { selector: "#uniqueId" } }, // Choose the type of mouse interaction for the triggering element. // When rightClick is true, pressing Shift+F10 or the Applications key will perform the same action as right clicking. leftClick: true, rightClick: false, // Specify the tag names for the parent and child elements that will be matched against when building the menu structure. tag: { parent: "ul", // Will become the container with role="menu" child: "a" // Will become the focusable active element with role="menuitem", "menuitemcheckbox", or "menuitemradio" }, // Set a custom event handler to process every time a menu item is activated. onActivate: function(event, triggerNode, RTI, boundElement, checked, set, isRadio) { // 'checked' reflects the current attribute value for the checkable item, and is always a number if applicable. // if 0, the checked state is "false". // if 1, the checked state is "true". // if 2, the checked state is "mixed". // The 'set' argument is a function that will set the checkable item to a new state. // The new value must be a string consisting of "false", "true", or "mixed". // E.G. set("false"), set("true"), or set("mixed") for checkbox menu items only. }, // Set the class name for the top level container element className: 'menu', // Set the class name for the screen reader accessible close link // This must match the class name for any close links or buttons within the menu content, which will cause close event binding to automatically occur when the content is rendered. closeClassName: "CloseDC", // Preload markup in the background when using the Fetch API to load external content. // For examples, view files within "Templates/Menus". preload: true, // Preload images in the background when using the Fetch API to load external content. // For examples, view files within "Templates/Menus". preloadImages: true, // Optionally run a script after the menu finishes rendering. afterRender: function(DC) { // DC.container includes the rendered menu content. }, // Optionally run a script after the menu is removed. afterRemove: function(DC) { // Do something. }, // Optionally specify a render and remove animation effect for the menu. // 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/Menus" 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" }</code></pre> </div> <h2>Programmatic control</h2> <div> <pre><code class="language-javascript">// Get the DC object for the top level menu using its id. var DC = $A("menuTriggerId"); // Open the menu manually. DC.render(function() { // Optionally do something after rendering completes. }); // Close the menu manually. DC.remove(function() { // Optionally do something after removal completes. }); // Additional DC API properties and methods can be applied here as well. // To view available options, reference the help docs located at: "Help/DC API/DC Object Properties and Methods"</code></pre> </div> </section> </main> </div> <footer class="footer"> <div class="flex-container-row"> <div class="flex-item"> <h2>License</h2> <p> Apex 4X including all template design patterns is distributed under the terms of the Open Source Initiative OSI - MIT License, and may be freely used for any purpose within any web technology. </p> </div> <div class="flex-item"> <h2>Resources</h2> <ul> <li> <a target="ext" href="https://github.com/WhatSock/apex" >Apex 4X on GitHub</a > </li> <li> <a target="ext" href="https://whatsock.github.io/visual-aria/github-bookmarklet/visual-aria.htm" >Visual ARIA Bookmarklet</a > </li> <li> <a target="ext" href="https://chrome.google.com/webstore/detail/visual-aria/lhbmajchkkmakajkjenkchhnhbadmhmk" >Visual ARIA Chrome Extension</a > </li> <li> <a target="ext" href="https://addons.mozilla.org/en-US/firefox/addon/visual-aria/" >Visual ARIA Firefox Extension</a > </li> <li> <a target="ext" href="https://github.com/AccDC/visual-aria" >Visual ARIA on GitHub</a > </li> <li> <a target="ext" href="https://whatsock.com/training/matrices/" >ARIA Role Conformance Matrices</a > </li> <li> <a target="ext" href="https://whatsock.com/training/" >Accessibility Tree Training Guide</a > </li> </ul> </div> <div class="flex-item"> <h2>Acknowledgements</h2> <ul class="list--horizontal"> <li> Author and developer: <a target="ext" href="https://www.linkedin.com/in/bgaraventa" >Bryan Garaventa</a > </li> <li> Website designer: <a target="ext" href="https://gericci.me/">Angela Ricci</a> </li> <li> Style and markup editor: <a target="ext" href="https://www.linkedin.com/in/laurence-lewis-77520365/" >Laurence Lewis</a > </li> </ul> </div> </div> </footer> </div> </body> <script async src="https://api.whatsock.com/accdc-updates.js?4x=template" ></script> </html>