apex4x

<!doctype html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>ARIA Tooltips - 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 Tooltips</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="Error (External)/index.htm">Error (External)</a></li> <li><a href="Error (Inline)/index.htm">Error (Inline)</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="Help (Responsive)/index.htm">Help (Responsive)</a> </li> <li><a href="Internal/index.htm">Internal</a></li> <li> <a href="Internal - Straylight/index.htm" >Internal - Straylight</a > </li> </ul> </nav> <section class="section--instructions"> <h2>Expected behaviors</h2> <ul> <li> Hover tooltips appear when moused over and when the triggering element receives focus, then close when the mouse moves away or when focus moves to a different element. </li> <li> Manual tooltips appear when the triggering element is activated, then close when clicked again or when focus moves to a different element. </li> <li> Responsive tooltips appear when validation criteria are met when typing, and close when focus moves to a different element. </li> <li> Error tooltips appear when focus moves away from a field that fails validation, then close when focus moves back to the triggering element. </li> </ul> <p> The 4X ARIA Tooltip 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 Tooltip module: </p> <ul> <li>role=tooltip</li> <li>aria-describedby</li> <li>aria-description</li> <li>role=region</li> <li>aria-label</li> </ul> <p>Available attributes for the triggering element:</p> <ul> <li> data-tooltip : The resource path and pointer to the ID attribute of the tooltip container element. May consist of a traditional id reference within the same document, or a url+id reference for pulling a tooltip in from an external resource, or the tooltip markup and message that should be displayed visually when triggered. </li> <li> data-error : The resource path and pointer to the ID attribute of the error container element. May consist of a traditional id reference within the same document, or a url+id reference for pulling an error tooltip in from an external resource, or the error tooltip markup and message that should be displayed visually when triggered. </li> </ul> <h2>HTML syntax</h2> <p>There are many options for setting the content of a tooltip.</p> <h3>Using embedded markup to create a tooltip</h3> <div> <pre><code class="language-markup"> <button data-tooltip='<p>Your email address is required to verify your account, but will not be used for any other purpose.</p>'> Why do we need this? </button> </code></pre> </div> <h3>Using CSS selector to reference a tooltip</h3> <div> <pre><code class="language-markup"> <label for="passwordId"> Password: </label> <input data-tooltip="#passwordTooltipId" id="passwordId" type="password"> </code></pre> </div> <div> <pre><code class="language-markup"> <div hidden id="passwordTooltipId"> <p> Important! </p> <ul> <li> Must be 8 characters in length.</li> <li> Must not contain special characters.</li> <li> Must not contain any whitespace characters.</li> </ul> </div> </code></pre> </div> <h3>Using URL+id to reference an external tooltip</h3> <div> <pre><code class="language-markup"> <button data-tooltip="url/tooltips.php?type=help#tooltipContainerId"> What is this? </button> </code></pre> </div> <h3> Using standard markup for any focusable element configured with JS setup script </h3> <div> <pre><code class="language-markup"> <a class="hasTooltip" href="URL"> ONE </a> </code></pre> </div> <div> <pre><code class="language-markup"> <button class="hasTooltip"> TWO </button> </code></pre> </div> <div> <pre><code class="language-markup"> <input class="hasTooltip" type="text" title="THREE" > </code></pre> </div> <p> The data-error attribute may be implemented using the same syntax as the data-tooltip attribute, and both data-error and data-tooltip attributes are supported on the same element. However, the data-error attribute is only valid on native input elements. </p> <h2>JavaScript syntax</h2> <div> <pre><code class="language-javascript">var myTooltipDC = $A.setTooltip( domNodeOrCSSSelectorForTriggeringElement , { // Configure functionality key / value mappings });</code></pre> </div> <ul> <li>Module file: Tooltip.js</li> <li>Has no dependencies.</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"> { // Unique ID for the tooltip instance id: "UniqueId", // Optionally specify the tooltip container element within the same document. // May be a DOM node or CSS selector. // Not necessary if data-tooltip or data-error is set on the triggering element. content: "#tooltipContainerId", // Optionally specify the tooltip to be rendered when referencing external content. // Not necessary if data-tooltip or data-error 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: "#tooltipContainerId" } }, // Optionally toggle the hidden attribute instead of inserting the tooltip 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, // Optionally specify if the tooltip is an alert message. // If true, a system alert will be fired when the tooltip is rendered. // As a general practice, tooltips and errors should never be alerts because this can interfere with speech announcement, so use with caution. isAlert: false, // Specify that the tooltip is an inline error message. isError: false, // Specify that the tooltip will only open when the triggering element receives focus, and not when moused over. isFocusOnly: false, // Specify that the tooltip will only open when the triggering element is clicked, and will close when clicked again. isManualOpen: false, // Specify that the tooltip will only close when the mouse leaves the tooltip instead of the triggering element. // Necessary to pass some WCAG guidelines. isManualClose: true, // Specify that the tooltip will be displayed only when specific validation criteria are met when typing. // Use when customized responses are needed to guide user input. // Only valid on editable native input elements. isResponsive: false, // Set validation criteria to pass or fail as needed. // Only applicable when isResponsive is set to true. // Only valid on editable native input elements. validate: function(DC, target) { // 'target' is the input element to validate. var val = target.value.toLowerCase(); // Set the DC.isValid property to track the state of validation. DC.isValid = val.length > 0; // Return the string to display as the tooltip if validation passes or failes. if (DC.isValid) return "You typed something!"; else return "This field desires input."; }, // Execute a handler every time validate is processed. // Only applicable when isResponsive is set to true. // Only valid on editable native input elements. onValidate: function(DC, target) { // Do something every time the target is updated. document.querySelector('input[type="submit"]').disabled = !DC.isValid; }, // Optionally specify a delay in milliseconds to wait before rendering the tooltip after the triggering element is activated. delay: 0, // Optionally specify a timeout length in milliseconds, after which the tooltip will automatically close. delayTimeout: 0, // Optionally override the default timeout function that occurs after the delayTimeout length is reached. timeout: function(dc) { // Do something... dc.remove(); }, // Optionally specify a render and remove animation effect for the tooltip. // 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/Tooltips" 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 run a script after the tooltip finishes rendering. afterRender: function(DC) { // DC.container includes the rendered tooltip content. }, // Optionally run a script after the tooltip is removed. afterRemove: function(DC) { // Do something. } // 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"> // Use the DC object that is returned by the $A.setTooltip() function. // Open the tooltip manually. myTooltipDC.render(function() { // Optionally do something after rendering completes. }); // Close the tooltip manually. myTooltipDC.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>