apex4x
Version:
The Comprehensive ARIA Development Suite
514 lines (444 loc) • 19.2 kB
HTML
<!doctype html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>ARIA Comboboxes - 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 Comboboxes</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 class="mobile--componentName">
<a href="../index.htm">Back to Components</a>
</li>
<li class="mobile--componentName">
<a href="Native%20Inputs,%20Editable%20and%20Readonly/index.htm"
>Native Inputs, Editable and Readonly</a
>
</li>
<li class="mobile--componentName">
<a
href="Native%20Inputs,%20Editable%20with%20Substring%20Match/index.htm"
>Native Inputs, Editable with Substring Match</a
>
</li>
<li class="mobile--componentName">
<a
href="Native%20Inputs,%20Editable%20with%20Word%20Match/index.htm"
>Native Inputs, Editable with Word Match</a
>
</li>
<li class="mobile--componentName">
<a
href="Native%20Inputs,%20Multiselect%20Editable%20with%20Substring%20Match/index.htm"
>Native Inputs, Multiselect Editable with Substring Match</a
>
</li>
<li class="mobile--componentName">
<a href="Simulated,%20Readonly/index.htm"
>Simulated, Readonly</a
>
</li>
<li class="mobile--componentName">
<a href="Simulated,%20Readonly%20Multiselect/index.htm"
>Simulated, Readonly Multiselect</a
>
</li>
</ul>
</nav>
<section class="section--instructions">
<h2>Expected behaviors</h2>
<ul>
<li>
All Combobox controls are keyboard focusable unless explicitly
disabled, and must include an accessible close or toggle icon
for sighted mouse and mobile touch device users when applicable.
</li>
<li>
Interactive editable Combobox controls that use an
Input+type=text element, open using the Down arrow, are
navigated using Up and Down, are saved and closed by pressing
Alt+Up or Enter, are canceled and closed by pressing Escape, and
support uninterrupted editability when Left or Right or any
other non-control key is pressed.
</li>
<li>
Interactive readonly Combobox controls that use an
Input+type=text element, open using the Down arrow, are
navigated using Up and Down, are saved and closed by pressing
Alt+Up or Enter, are canceled and closed by pressing Escape, and
require a toggleable triggering element for sighted mouse and
mobile touch device users.
</li>
<li>
Interactive Combobox controls that use simulated active elements
such as Divs or Spans, are readonly by default, open using the
Down arrow or Enter key, are navigated using Up and Down, are
saved and closed by pressing Alt+Up or Enter, are canceled and
closed by pressing Escape, and act as their own actionable
toggle control.
</li>
</ul>
<p>
The 4X ARIA Combobox module automatically configures all required
ARIA attributes and focus handling, in strict accordance with the
ARIA 1.2 specification.
</p>
<p>
The following attributes are handled automatically by the Combobox
module:
</p>
<ul>
<li>role=combobox</li>
<li>aria-activedescendant</li>
<li>aria-expanded</li>
<li>aria-controls</li>
<li>aria-autocomplete</li>
<li>aria-haspopup</li>
<li>aria-description</li>
<li>role=listbox</li>
<li>role=option</li>
<li>tabindex</li>
</ul>
<h2>HTML syntax</h2>
<div>
<pre><code class="language-markup">
<label for="comboboxId"> Unique Name: </label>
<input type="text" id="comboboxId" >
</code></pre>
</div>
<p>
For simulated active elements, any combination of HTML container
markup with embedded tags is supported.
</p>
<div>
<pre><code class="language-markup">
<div title="Set your location" id="comboboxId">
<span id="valueTextId">
<!-- Selected values will be dynamically inserted here. -->
</span>
</div>
</code></pre>
</div>
<p>
IMPORTANT: The focusable combobox element must not include any
other active elements, otherwise these will not be accessible to
non-sighted screen reader users.
</p>
<p>
It is equally important not to use aria-label on the simulated
combobox to set the accessible name. Otherwise, it will prevent
non-sighted screen reader users from being able to read the
current value within the embedded markup.
</p>
<h3>Hidden Select element</h3>
<p>
All Combobox controls are bound to a standard Select element
instance, which may be hidden within the page, or dynamically
generated using JavaScript to support dynamic population via AJAX.
</p>
<div>
<pre><code class="language-markup">
<select hidden id="hiddenSelectId">
<option value="value1"> ONE </option>
<option value="value2"> TWO </option>
</select>
</code></pre>
</div>
<p>
To enable multiselect functionality, add the 'multiple' attribute
to the hidden select element.
</p>
<p>
To set a default value for the Combobox other than index[0], add
the 'selected' attribute to the default option.
</p>
<h2>JavaScript syntax</h2>
<div>
<pre><code class="language-javascript">
var myCombobox = new $A.Combobox({
select: $A.get("hiddenSelectId"), // Required
input: $A.get("comboboxId"), // Required
childNode: $A.get("valueTextId"), // For simulated comboboxes only.
override: {
// DC API overrides
}
});
// Configure settings here prior to invocation
// Then invoke the Combobox for auto-rendering when interacted with.
myCombobox.start();
</code></pre>
</div>
<ul>
<li>Module file: Combobox.js</li>
<li>
Requires: Velocity.js, VelocityUI.js, Animate.js,
SmoothScroll.js, AccName.js, CurrentDevice.js.
</li>
</ul>
<h2>Parameters</h2>
<ol>
<li>A configuration map to customize behaviors and options</li>
</ol>
<h3 tabindex="-1" id="configure">Configuration</h3>
<div>
<pre><code class="language-javascript">{
// The hidden Select element DOM node that will be bound to the Combobox control.
select: selectElementDOMNode ,
// The focusable role=combobox element that will be bound to the hidden Select element.
input: inputDOMNode ,
// The embedded child container element where the value text will be dynamically updated. This is only applicable when the combobox element is not a native HTML input or textarea element.
childNode: optionalChildDOMNode,
// An optional override of DC object properties and methods when instantiated.
override: {
// DC API overrides
}
}</code></pre>
</div>
<h2>Programmatic control</h2>
<p>
After a Combobox control is instantiated, the following public
properties and methods are available.
</p>
<h3>Methods</h3>
<div>
<pre><code class="language-javascript">// Set the listbox to render all Select Options regardless of the current value
myCombobox.setShowAll(Boolean); // Default: False
// Enable full listbox content browsing from the keyboard when the down arrow key is pressed. (Applicable only when the value is empty.)
myCombobox.setShowAllIfEmpty(Boolean); // Default: False
// Set the listbox to render only Select Options that match the substring value
myCombobox.setSubstringMatch(Boolean); // Default: False
// Set the listbox to render only Select Options that include all of the space delimited words in the current value
myCombobox.setWordMatch(Boolean); // Default: False
// Set the Combobox to automatically display the currently selected value within the hidden Select element onStart
myCombobox.setDefault(Boolean); // Default: True
// Set the currently selected listbox value to automatically be saved when focus moves away from the Combobox control
myCombobox.setAutoComplete(Boolean); // Default: False
// Set the parent/child tag markup structure for the dynamically rendered listbox
myCombobox.setTags({
parentTag: 'ul',
childTag: 'li'
});
// Set dynamic class names
myCombobox.setClassNames({
toplevelClass: 'toplevel-div clearfix', // Top level Div class of Combobox listbox
middleClass: 'middle-div clearfix', // Mid level Div class of Combobox listbox
listboxClass: 'listbox clearfix', // // parentTag class
optionClass: 'option clearfix', // childTag class
activeClass: 'active', // Currently active Combobox listbox option
toggleClass: 'pressed' // Pressed state class of the altTrigger element
});
// Set CSS autopositioning relative to the triggering Combobox element.
// Accepted 4X API values between 0-disabled-default and 12
// For details, view the help doc at: Help/DC API/DC Object Configuration/Visual Effects
myCombobox.setAutoPosition(Number); // Default: 0
// Set a positive or negative top/left offset to be applied to the autoPosition property calculation
myCombobox.setOffset({
top: Number,
left: Number
});
// Set the number of listbox options to render when displayed
myCombobox.setSize(Number); // Default: 5
// Set a different element to act as an autoPosition focus element instead of the Combobox control
myCombobox.setPosAnchor(alternateDOMNode); // Will not change the DOM insertion point and reading order
// Set a different element to act as an insertion point and autoPosition focus element instead of the Combobox control
myCombobox.setTargetNode(alternateDOMNode); // Will change the DOM reading order
// Invoke the Combobox control and apply all saved settings
myCombobox.start();
// Close the Combobox control and pause functionality
myCombobox.stop();
// Manually open the Combobox listbox using all applied settings
myCombobox.open();
// Set a handler to execute every time the Combobox listbox is rendered
myCombobox.onOpen(function(dc){
// this = the Combobox control
// dc = the DC object instance for the Combobox listbox
});
// Manually close the Combobox listbox
myCombobox.close();
// Set a handler to execute every time the Combobox listbox is closed
myCombobox.onClose(function(dc){
// this = the Combobox control
// dc = the DC object instance for the Combobox listbox
});
// Set a toggle control to open or close the Combobox listbox
// Must always be set when implementing readonly Input+type=text elements to ensure sighted mouse and mobile touch device support
myCombobox.setAltTrigger(toggleElementDOMNode);
// Set a handler to execute every time the toggle altTrigger element is activated
myCombobox.onTriggerChange(function(altTriggerElement, toggleState){
// this = altTriggerElement
// toggleState = true or false
});
// Set a handler to execute every time a new value is saved to the Combobox control
// This will override the default functionality
myCombobox.onSelect(function(optionName, optionValue, comboboxControl, selectElement){
// this = comboboxControl
// optionName = the visible string for the hidden Select option that is highlighted.
// optionValue = the value attribute for the hidden Select option that is selected. This parameter changes to an array of selected option nodes when multiple is set instead.
// comboboxControl = the Combobox control element
// selectElement = the hidden Select element
// Save the new value accordingly
// then return the saved string to prevent auto rerendering of the Combobox listbox
return 'saved string';
});
// Set multiple divider to break up list item markup properly when updated.
// Automatically becomes available when the multiple attribute is set on the hidden select element.
myCombobox.setMultipleDivider(function(values){
// 'values' is an array of string names for the selected option nodes.
return values.join(' ');
});
// Clear all selected options when multiple is set on the hidden select element.
myCombobox.clearAll();
// Enable auto saving of checked options, even when typing to narrow the filtered list of options at the same time.
// Applicable only when Multiselect is enabled.
myCombobox.setAutoSaveIfChecked(Boolean); // Default: False
// Set a character minimum when typing into an editable combobox before autosuggested options are rendered.
myCombobox.setCharMin(
// Get the current value of the hidden select element
// Returns a value property string for single select elements, or an array of selected option DOM nodes when the multiple attribute is set on the select element.
myCombobox.getValue();
// Manually resynchronize the hidden Select to rebuild available Options for the Combobox listbox
// This can be used to repopulate rendered options after remote API queries via AJAX cause the hidden Select to contain new Options
myCombobox.update();
// Set a string to be announced to screen reader users when the Combobox control receives focus
myCombobox.setPromptText(String); // Default: ''
// Set a name for the offscreen Close link for screen reader users
// Necessary for non-sighted touch screen device users to detect the end of the Combobox listbox when rendered
// To disable the offscreen Close link when needed, pass a null value ("") to the method.
myCombobox.setCloseText(String); // Default: 'Close Popup'</code></pre>
</div>
<h3>Properties</h3>
<div>
<pre><code class="language-javascript">// Access the hidden Select element DOM node
var selectElement = myCombobox.select;
// Access the role=combobox element DOM node
var comboboxElement = myCombobox.combobox;</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>