apex4x
Version:
The Comprehensive ARIA Development Suite
450 lines (391 loc) • 16.7 kB
HTML
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>ARIA Accordions - 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/css/components-style.css"
/>
<link
rel="stylesheet"
type="text/css"
href="../_common/_doc_files/prism.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 Accordions</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="Internal - Single Tab Stop/index.htm"
>Internal - Single Tab Stop</a
>
</li>
</ul>
</nav>
<section class="section--instructions">
<h2>Expected behaviors</h2>
<p>
All accordion triggering elements should be in the tab order,
pressing Enter or Space should expand the desired accordion panel,
the expanded state should be toggled appropriately on the
triggering element, and the expanded accordion panel should be
rendered directly after the triggering element in the tab order.
</p>
<p>
Though similar in both concept and execution to Tab controls,
accordions are not the same. A Tab control has a series of grouped
triggering elements that expand and collapse, the rendered content
of which is inserted directly after the triggering element group
when opened. The container element insertion point for all Tab
control triggering elements is shared between them. Also, the
group of triggering elements in a Tab control has only one tab
stop. The arrow keys are then used to switch focus between each
Tab, and the Enter or Space key is used to expand the desired Tab
content panel.
</p>
<p>
In contrast, an Accordion has a series of triggering elements that
expand and collapse, the rendered content of which is inserted
directly after the triggering element when opened. The container
element insertion points for Accordions are not shared. Also, all
Accordion links appear in the tab order. The reason why ARIA
attributes such as role="tablist" and role="tab" are not included
within accordions, is because the insertion of inline content
would place dynamic content sections within the same Tablist
container, making it impossible to determine the order of nested
Tab controls when present within the inserted content. The chosen
implementation should always match the UI that it's being applied
to, to prevent confusion.
</p>
<p>
The 4X ARIA Accordion module automatically configures all required
ARIA attributes and focus handling, in strict accordance with the
ARIA specification.
</p>
<p>
Note: An accordion is a composite widget, meaning that it is
comprised of different ARIA roles and supporting attributes.
</p>
<p>
The following attributes are handled automatically by the
Accordion module:
</p>
<ul>
<li>role=button</li>
<li>aria-expanded</li>
<li>aria-controls</li>
<li>role=region</li>
<li>aria-labelledby</li>
<li>tabindex</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 accordion container element.
</li>
<li>
data-root : The ID attribute of the container element where the
accordion content will be inserted when rendered. (This must not
be inside the triggering element)
</li>
<li>
data-active : Specifies that the referenced accordion node will
open automatically. Only one accordion node per group should
include this attribute.
</li>
<li>
aria-disabled : When set to "true" on the triggering element,
will automatically disable associated functionality.
</li>
</ul>
<p>
Note: When dynamically disabling a triggering element, the 4X
setDisabled() function should be used to set the disabled state of
the triggering element. This will ensure proper background
mapping.
</p>
<div>
<pre><code class="language-javascript">
$A.setDisabled(triggeringElement, boolean);
</code></pre>
</div>
<h2>HTML syntax</h2>
<div>
<pre><code class="language-markup"><h2>
<button data-active data-root="root-id-for-billing" data-controls="accordion-panel-id-for-billing" > BILLING </button>
</h2>
<div id="root-id-for-billing">
<div id="accordion-panel-id-for-billing">
Expandable content for the billing section here. (Content visible by default via the data-active attribute on the triggering element.)
</div>
</div>
<h2>
<button data-root="root-id-for-shipping" data-controls="accordion-panel-id-for-shipping" > SHIPPING </button>
</h2>
<div id="root-id-for-shipping">
<div hidden id="accordion-panel-id-for-shipping">
Expandable content for the shipping section here. (Content hidden by default via the hidden attribute on the accordion panel.)
</div>
</div></code></pre>
</div>
<p>
IMPORTANT: The triggering element must not include any other
active elements, otherwise these will not be accessible to
non-sighted screen reader users.
</p>
<p>
When aria-disabled="true" is set on an accordion triggering
element, functionality for that accordion panel will automatically
be disabled.
</p>
<h2>JavaScript syntax</h2>
<div>
<pre><code class="language-javascript">$A.setAccordion( domNodeListOrCSSSelectorForTriggeringElements , {
// Configure functionality key / value mappings
});</code></pre>
</div>
<ul>
<li>Module file: Accordion.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 elements
</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 single tab stop for associated accordion triggering elements.
singleTabStop: false,
// Auto configure orientation using dynamic switching based on the visual layout of focusable elements.
// Only applicable when singleTabStop is true.
// "off"=Inactive, "semi"=Switches between vertical and horizontal only, "full"= Switches between vertical, horizontal, and both when line-wrapping is detected.
autoSwitch: "full",
// Optionally extend the RTI instance with custom event handlers.
// Only applicable when singleTabStop is true.
// For available options, view the RovingTabIndex help doc at "Help/Module Imports/Actions/RovingTabIndex".
extendRTI: {
// Optional event handlers.
},
// Optionally choose to track the browser history when each panel is opened.
// May be used to automatically open the same panel after the page is bookmarked.
// Requires that each accordion triggering element include a unique id attribute.
trackPage: false,
// Toggle the specified class name on the triggering element when hidden or shown.
toggleClassName: "open",
// Optionally toggle the hidden attribute instead of inserting the accordion panel when rendered.
toggleHide: false,
// Specify that the collection of accordion triggering elements will function like toggles, where the currently open panel can be closed.
isToggle: false,
// Specify that the collection of accordion triggering elements will function as independant objects, where multiple panels may be open at the same time.
allowMultiple: 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 accordion panel finishes rendering.
afterRender: function(DC) {
// DC.container includes the rendered accordion content.
},
// Optionally run a script after the accordion panel is removed.
afterRemove: function(DC) {
// Do something.
},
/*
// Enable auto-rendering when the page loads.
// When true, the hash tag in the URL will automatically open the associated DC object.
// To render automatically, the hash tag must match the DC object id.
// To set a hash tag within the address bar, use the $A.setPage() function.
// For more details, view: Help/ARIA Development/Browser History and Permalinks
// Plus: Help/DC API/DC Object Configuration/Behaviors
trackPage: true,
afterRender: function(dc) {
$A.setPage(
dc.id,
$A.getText(dc.triggerNode) + " ARIA Accordion - Apex 4X Technical Style Guide"
);
},
*/
// Optionally specify a render and remove animation effect for the accordion.
// 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/Accordions" 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">// Get the DC object for the accordion using its triggering element id.
var DC = $A("accordionTriggerId");
// Open the accordion manually.
DC.render(function() {
// Optionally do something after rendering completes.
});
// Close the accordion 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>