apex4x
Version:
The Comprehensive ARIA Development Suite
388 lines (333 loc) • 13.2 kB
HTML
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>ARIA Popups - 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 Popups</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 - Alert/index.htm">Internal - Alert</a></li>
<li>
<a href="Internal - Straylight/index.htm"
>Internal - Straylight</a
>
</li>
</ul>
</nav>
<section class="section--instructions">
<h2>Expected behaviors</h2>
<p>
Move focus into the popup when it is rendered, ensure that the
beginning and ending boundaries are conveyed to screen reader
users, make sure the popup can be closed from the keyboard, ensure
that circular tabbing confines keyboard focus within the popup
content, and move focus back to the triggering element after the
popup is removed.
</p>
<p>
The 4X ARIA Popup 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 Popup
module:
</p>
<ul>
<li>role=region</li>
<li>aria-labelledby</li>
<li>aria-expanded</li>
</ul>
<p>Available attributes for the triggering element:</p>
<ul>
<li>
data-controls : The resource path and pointer to the ID
attribute of the popup container element. May consist of a
traditional id reference within the same document, or a url+id
reference for pulling a popup in from an external resource. E.G.
data-controls="path/get.php?type=moreInfo#popupContainerId"
</li>
</ul>
<h2>HTML syntax</h2>
<h3>Triggering Element</h3>
<div>
<pre><code class="language-markup">
<button id="popupTriggerId"> MORE INFO </button>
</code></pre>
</div>
<p>
To ensure the greatest level of accessibility, a triggering
element should always consist of a native button or link.
</p>
<h3>Popup Container</h3>
<div>
<pre><code class="language-markup">
<div hidden id="popupId">
<button aria-label="Close" class="CloseDC"><!-- Close Icon Here --></button>
<div> Popup content... </div>
</div>
</code></pre>
</div>
<p>
When Implementing a Close link or button, the className must match
the "closeClassName" property within the script declaration. Doing
so will automatically bind the close methods with this element,
and set keyboard focus properly when the popup is closed. If
closeClassName is not specified, the default class will be set to
"CloseDC" instead. The aria-label attribute provides an
informative name for non-sighted screen reader users no matter
what the visible icon is set to.
</p>
<h2>JavaScript syntax</h2>
<div>
<pre><code class="language-javascript">
var myPopupDC = $A.setPopup( "#popupTriggerId", {
// Configure functionality key / value mappings
});
</code></pre>
</div>
<ul>
<li>Module file: Popup.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 popup instance
id: "UniqueId",
// Specify the role name for the popup that will be conveyed to screen reader users. E.G. "Movie Details"
role: "Popup Purpose",
// Optionally specify the popup container element within the same document.
// May be a DOM node or CSS selector.
// Not necessary if data-controls is set on the triggering element.
content: "#popupId",
// Optionally specify the popup to be rendered when referencing external content.
// Not necessary if data-controls 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: "#popupId"
}
},
// 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 popup content, which will cause close event binding to automatically occur when the content is rendered.
closeClassName: "CloseDC",
// Optionally specify if the popup is an alert message.
// If true, a system alert will be fired when the popup is rendered.
isAlert: false,
// Optionally toggle the hidden attribute instead of inserting the popup content when rendered.
toggleHide: false,
// 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 run a script after the popup finishes rendering.
afterRender: function(DC) {
// DC.container includes the rendered popup content.
},
// Optionally run a script after the popup is removed.
afterRemove: function(DC) {
// Do something.
},
// Optionally specify a delay in milliseconds to wait before rendering the popup after the triggering element is activated.
delay: 0,
// Optionally specify a timeout length in milliseconds, after which the popup will automatically close.
delayTimeout: 0,
// Optionally override the default timeout function that occurs after the delayTimeout length is reached.
timeout: function(dc) {
dc.remove();
},
// Optionally specify a render and remove animation effect for the popup.
// 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/Popups" 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.
}
});
}
}
// 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.setPopup() function.
// Open the popup manually.
myPopupDC.render(function() {
// Optionally do something after rendering completes.
});
// Close the popup manually.
myPopupDC.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>