-
Notifications
You must be signed in to change notification settings - Fork 285
/
Copy pathARIA1.html
244 lines (218 loc) · 12.7 KB
/
ARIA1.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
<!DOCTYPE html><html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"><head><title>Using the aria-describedby property to provide a descriptive label for user interface controls</title><link rel="stylesheet" type="text/css" href="../../css/sources.css" class="remove"></link></head><body><h1>Using the aria-describedby property to provide a descriptive label for user interface controls</h1><section class="meta"><p class="id">ID: ARIA1</p><p class="technology">Technology: aria</p><p class="type">Type: Technique</p></section><section id="applicability"><h2>When to Use</h2>
<p>Technologies that support <a href="https://www.w3.org/TR/wai-aria/">Accessible Rich Internet Applications (WAI-ARIA)</a>. </p>
</section><section id="description"><h2>Description</h2>
<p>The purpose of this technique is to demonstrate how to use the WAI-ARIA <a href="https://www.w3.org/TR/wai-aria/states_and_properties#aria-describedby">aria-describedby</a> property to provide programmatically determined, descriptive information about a user interface element. The <code class="att">aria-describedby</code> property may be used to attach descriptive information to one or more elements through the use of an id reference list. The id reference list contains one or more unique element ids. </p>
<p>Refer to <a href="https://www.w3.org/TR/wai-aria-primer/#ariahtml">Supporting ARIA in XHTML and HTML 4.01</a> for information on how to provide WAI-ARIA States and Properties with XHTML and HTML. WAI-ARIA States and Properties is compatible with other languages as well; refer to documentation in those languages. </p>
<div class="note">
<p>The <code class="att">aria-describedby</code> property is not designed to reference descriptions on an external resource — since it is an ID, it must reference an element in the same DOM document.</p>
</div>
</section><section id="examples"><h2>Examples</h2>
<section class="example">
<h3>Using aria-describedby property to describe a Close button's action</h3>
<p>A button that functions as a 'close' button on a dialog is described elsewhere in the document. The <code class="att">aria-describedby</code> property is used to associate the description with the link.</p>
<pre xml:space="preserve"><button aria-label="Close" aria-describedby="descriptionClose"
onclick="myDialog.close()">X</button>
...
<div id="descriptionClose">Closing this window will discard any information entered and
return you back to the main page</div>
</pre>
<p class="working-example">Working example: <a href="../../working-examples/aria-describedby-close/">Example 1</a>
</p>
</section>
<section class="example">
<h3>Using aria-describedby to associate instructions with form fields</h3>
<p>Sample form field using <code class="att">aria-describedby</code> to associate instructions with form fields while there is a form label.</p>
<pre xml:space="preserve"><form>
<label for="fname">First name</label>
<input name="" type="text" id="fname" aria-describedby="int2">
<p id="int2">A bit of instructions for this field linked with aria-describedby. </p>
</form>
</pre>
</section>
<section class="example">
<h3>Using aria-describedby property to provide more detailed information about the button</h3>
<pre xml:space="preserve"><p><span id="fontDesc">Select the font faces and sizes to be used on this page</span>
<button id="fontB" onclick="doAction('Fonts');" aria-describedby="fontDesc">Fonts</button>
</p>
<p><span id="colorDesc">Select the colors to be used on this page</span>
<button id="colorB" onclick="doAction('Colors');" aria-describedby="colorDesc">Colors</button>
</p>
<p><span id="customDesc">Customize the layout and styles used on this page</span>
<button id="customB" onclick="doAction('Customize');" aria-describedby="customDesc">Customize</button>
</p>
</pre>
</section>
<section class="example">
<h3>Using aria-describedby to associate tooltips with form fields</h3>
<p>The following code snippet shows how to use <code class="att">aria-describedby</code> and the onfocus="tooltipShow() function to display the tooltip when focus is placed on an element.</p>
<pre xml:space="preserve"><html lang="en-us">
<head>
<title>inline: Tooltip Example 1</title>
<link rel="stylesheet" href="css/tooltip1_inline.css" type="text/css">
<script type="text/javascript" src="js/tooltip1_inline.js"></script>
<script type="text/javascript" src="../js/widgets_inline.js"></script>
<script type="text/javascript" src="../js/globals.js"></script>
<link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">
</head>
...
<body onload="initApp()">
<div id="container">
<h1>Tooltip Example 1</h1>
<h2>Create Account</h2>
<div class="text">
<label for="first">First Name:</label>
<input type="text" id="first" name="first" size="20"
onmouseover="tooltipShow(event, this, 'tp1');"
onfocus="tooltipShow(event, this, 'tp1');"
aria-describedby="tp1"
aria-required="false"/>
<div id="tp1" role="tooltip" aria-hidden="true">Your first name is optional. </div>
</div>
</pre>
</section>
<section class="example">
<h3>XHTML</h3>
<p>This example is coded in XHTML with a MIME type of application/xhtml+xml. This MIME type is not supported in all user agents. The aria-describedby property is added directly into the XHTML markup, and no additional scripting is needed. </p>
<pre xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+ARIA 1.0//EN"
"https://www.w3.org/WAI/ARIA/schemata/xhtml-aria-1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8" />
<title>Demonstration of aria-describedby property</title>
<style type="text/css">
div.form p { clear:left; margin: 0.3em 0;}
.left {
float:left;
width:400px;
}
.right {
width:100px;
text-align:right;
}
</style>
</head>
<body>
<p>The buttons on this page use the Accessible Rich Internet Applications aria-describedby property
to provide more detailed information about the button action</p>
<div class="form">
<p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
<span class="right"><button id="fontB" onclick="doAction('Fonts');" aria-describedby="fontDesc">
Fonts </button></span></p>
<p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
<span class="right"><button id="colorB" onclick="doAction('Colors');" aria-describedby="colorDesc">
Colors </button></span></p>
<p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
<span class="right"><button id="customB" onclick="doAction('Customize');" aria-describedby="customDesc">
Customize </button></span></p>
</div>
</body>
</html>
</pre>
</section>
<section class="example">
<h3>HTML</h3>
<p>This example uses scripting to add an aria-describedby property to buttons on a page. The example creates a buttonIds array variable to hold the ids of the elements that contain description text. The setDescribedBy() function is called from the onload event of the window object. </p>
<p>The setDescribedBy() function loops through all of the button elements and calls setAttribute() on each button element to set the aria-describedby property. Each button's aria-describedby property is set to the id of the element containing its descriptive text. </p>
<p>Using a user agent and/or assistive technology which supports WAI-ARIA, the description will be provided when the user interface controls receive focus. </p>
<pre xml:space="preserve"><html lang="en-us">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>Demonstration of aria-describedby property</title>
<style type="text/css">
div.form p { clear:left; margin: 0.3em 0;}
.left {
float:left;
width:400px;
}
.right {
width:100px;
text-align:right;
}
</style>
<script type="text/javascript">
//<![CDATA[
// array entries for each button on the page that associates the button id
// with the id of the element containing the text which describes the button
var buttonIds = new Array();
buttonIds["fontB"]= "fontDesc";
buttonIds["colorB"] = "colorDesc";
buttonIds["customB"] = "customDesc";
// function that is run after the page has loaded to set the aria-describedBy
// property on each of the elements referenced by the array of id values
function setDescribedBy(){
if (buttonIds){
var buttons = document.getElementsByTagName("button");
if (buttons){
var buttonId;
for(var i=0; i<buttons.length; i++){
buttonId = buttons[i].id;
if (buttonId && buttonIds[buttonId]){
buttons[i].setAttribute("aria-describedby", buttonIds[buttonId]);
}
}
}
}
}
// simulated action function - currently just displays an alert
function doAction(theAction){
alert("Perform the " + theAction + " action");
}
window.onload=setDescribedBy;
//]]>
</script>
</head>
<body>
<p>The buttons on this page use the Accessible Rich Internet Applications
aria-describedby property to provide more detailed information
about the button action.
</p>
<div class="form">
<p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
<span class="right"><button id="fontB" onclick="doAction('Fonts');"> Fonts </button></span>
</p>
<p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
<span class="right"><button id="colorB" onclick="doAction('Colors');"> Colors </button></span>
</p>
<p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
<span class="right"><button id="customB" onclick="doAction('Customize');"> Customize </button></span>
</p>
</div>
</body>
</pre>
</section>
</section><section id="tests"><h2>Tests</h2>
<section class="procedure"><h3>Procedure</h3>
<ol>
<li>Check that there is a user interface control having an <code class="att">aria-describedby</code> attribute that references one or more elements via unique id.</li>
<li>Check that the referenced element or elements provide additional information about the user interface control.</li>
</ol>
</section>
<section class="results"><h3>Expected Results</h3>
<ul>
<li>Checks #1 and #2 are true. </li>
</ul>
</section>
</section><section id="related"><h2>Related Techniques</h2><ul>
<li><a href="../aria/ARIA2">ARIA2</a></li>
<li><a href="../aria/ARIA7">ARIA7</a></li>
</ul></section><section id="resources"><h2>Resources</h2>
<ul>
<li>
<a href="https://www.w3.org/WAI/intro/aria">WAI-ARIA Overview</a>
</li>
<li>
<a href="https://www.w3.org/TR/wai-aria-practices/">WAI-ARIA Authoring Practices 1.1</a>
</li>
<li>
<a href="https://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation">HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation</a>
</li>
<li>
<a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute">Using the aria-describedby attribute (MDN)</a>
</li>
<li>
<a href="https://www.w3.org/TR/aria-in-html/">Using WAI-ARIA in HTML</a>
</li>
</ul>
</section></body></html>