forked from w3c/aria-practices
/
aria-practices-DeletedSectionsArchive.html
3655 lines (3454 loc) · 318 KB
/
aria-practices-DeletedSectionsArchive.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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>Content Deleted From WAI-ARIA Authoring Practices 1.1</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script src="common/script/resolveReferences.js" class="remove"></script>
<script src="common/biblio.js" class="remove"></script>
<script class="remove">
var respecConfig = {
// Embed RDFa data in the output.
doRDFa : '1.1',
includePermalinks : true,
permalinkEdge : true,
permalinkHide : false,
// Specification status (e.g., WD, LC, NOTE, etc.). If in doubt use ED.
specStatus : "ED",
// crEnd: "2012-04-30",
// perEnd: "2013-07-23",
// publishDate: "2013-08-22",
noRecTrack : true,
diffTool : "http://www.aptest.com/standards/htmldiff/htmldiff.pl",
// The specifications short name, as in http://www.w3.org/TR/short-name/
shortName : "wai-aria-practices-1.1",
// If you wish the publication date to be other than today,
// set publishDate.
// publishDate: "2009-08-06",
copyrightStart : "2015",
// If there is a previously published draft, uncomment this
// and set its YYYY-MM-DD date and its maturity status.
//
// previousPublishDate: "",
// previousMaturity: "",
// prevRecURI: "",
// previousDiffURI: "",
// If there a publicly available Editors Draft, this is the link
edDraftURI : "http://w3c.github.io/aria-practices/",
// If this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2012-02-21",
// Editors, add as many as you like.
// “name” is the only required field.
editors : [ {
name : "Matt King",
mailto : "mck@fb.com",
company : "Facebook",
companyURI : "http://www.facebook.com/"
}, {
name : "James Nurthen",
mailto : "james.nurthen@oracle.com",
company : "Oracle Corporation",
companyURI : "http://www.oracle.com/"
}, {
name : "Michael Cooper",
url : 'http://www.w3.org/People/cooper/',
mailto : "cooper@w3.org",
company : "W3C",
companyURI : "http://www.w3.org/"
}, {
name : "Michiel Bijl",
mailto : "mbijl@paciellogroup.com",
company : "The Paciello Group",
companyURI : "https://www.paciellogroup.com/"
}, {
name : "Joseph Scheuhammer",
company : "Inclusive Design Research Centre, OCAD University",
companyURI : "http://idrc.ocad.ca/",
note : "Previous Editor"
}, {
name : "Lisa Pappas",
company : "SAS",
companyURI : "http://www.sas.com/",
note : "Previous Editor"
}, {
name : "Rich Schwerdtfeger",
company : "IBM Corporation",
companyURI : "http://ibm.com/",
note : "Previous Editor"
}, ],
// Authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// Same format and requirements as editors.
// authors: [
// {
// name: "Your Name",
// url: "http://example.org/",
// company: "Your Company",
// companyURI: "http://example.com/"
// },
// ],
// Spec URLs
ariaSpecURLs : {
"ED" : "http://w3c.github.io/aria/aria/aria.html",
"FPWD" : "http://www.w3.org/TR/wai-aria-1.1/",
"WD" : "http://www.w3.org/TR/wai-aria-1.1/",
"REC" : "http://www.w3.org/TR/wai-aria/"
},
accNameURLs : {
"ED" : "http://w3c.github.io/aria/accname-aam/accname-aam.html",
"WD" : "http://www.w3.org/TR/accname-aam-1.1/",
"FPWD" : "http://www.w3.org/TR/accname-aam-1.1/",
"REC" : "http://www.w3.org/TR/accname-aam-1.1/"
},
coreMappingURLs : {
"ED" : "http://w3c.github.io/aria/core-aam/core-aam.html",
"WD" : "http://www.w3.org/TR/core-aam-1.1/",
"FPWD" : "http://www.w3.org/TR/core-aam-1.1/",
"REC" : "http://www.w3.org/TR/core-aam-1.1/"
},
// alternateFormats: [
// {
// uri: 'aria-practices-diff.html',
// label: "Diff from Previous Recommendation"
// },
// {
// uri: 'aria-practices.ps',
// label: "PostScript version"
// },
// {
// uri: 'aria-practices.pdf',
// label: "PDF version"
// }
// ],
// errata: 'http://www.w3.org/2010/02/rdfa/errata.html',
// name of the WG
wg : "Accessible Rich Internet Applications Working Group",
// URI of the public WG page
wgURI : "http://www.w3.org/WAI/ARIA/",
// Name (without the @w3c.org) of the public mailing
// to which comments are due.
wgPublicList : "public-aria",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI
// from a random document unless you know what you're doing.
// If in doubt ask your friendly neighbourhood Team Contact.
wgPatentURI : "http://www.w3.org/2004/01/pp-impl/83726/status",
maxTocLevel : 4,
localBiblio : biblio,
preProcess : [ linkCrossReferences ]
};
</script>
<link href="common/css/common.css" rel="stylesheet" type="text/css" />
</head>
<body>
<section id="abstract">
<p>
This document is a placeholder for sitnificatn sections of content that were removed from the ARIA Authoring Practices Guide.
It allows reviewers to more easily see what was removed, and makes it easier to restore content.
</p>
</section>
<section id="aria_ex">
<h2>Design Patterns and Widgets</h2>
<section class="widget" id="autocomplete">
<h3>Auto Complete</h3>
<p class="note">This section has not been updated since it was integrated from APG
version 1.0 -- an APG task force review is pending.</p>
<p>A text box and an associated drop-down list of choices where the choices offered
are filtered based on the information typed into the box. Typically, an icon
associated with the text box triggers the display of the drop-down list of choices.
An editable auto-complete accepts text entry of choices that are not in the list. An
example of an editable auto-complete is the URL field in the browsers.</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>With focus in an empty text box, press <kbd>Down Arrow</kbd>, <kbd>Up
Arrow</kbd>, <kbd>Alt + Down Arrow</kbd>, or <kbd>Alt + Up Arrow</kbd> to
display the entire list of choices. Focus remains in the text box and no
choice is highlighted.
<ul>
<li>Press the <kbd>Down Arrow</kbd> to highlight the first choice
in the list.
</li>
<li>Press the <kbd>Down Arrow</kbd> and <kbd>Up Arrow</kbd> keys to
highlight the desired choice in the list.
</li>
<li>Note that the arrows will wrap through the text box when the
top or bottom of the list is reached. For example, pressing the down
arrow when the last choice is highlighted will move focus back to
the text box, pressing down again will move focus to the first item
in the list. Likewise, with focus in the text box and the list
displayed, pressing up arrow will move focus to the last item in the
list.</li>
<li>When a choice is highlighted using the arrow keys, the
highlighted choice is displayed in the text box.</li>
<li>Press <kbd>Enter</kbd> to select the highlighted choice and
close the drop-down list. This mimics the behavior of the HTML
select element.
</li>
</ul>
</li>
<li>With the drop-down list of choices displayed, move the mouse pointer
over an item in the list to highlight it. The text box value is not modified
when the mouse is used to highlight a choice. Clicking on the highlighted
choice will close the drop-down and update the text box with the selected
choice. This mimics the behavior of the HTML select element.</li>
<li>With focus in an empty text box, type <strong>any letter</strong>. If
any of the available choices begin with the letter typed, those choices are
displayed in a drop down. If the letter typed does not match any of the
available choices the drop-down list is not displayed.
</li>
<li>With focus in text box with an existing value type <strong>additional
letters.</strong> As the user types letters the list of choices is filtered so
that only those that begin with the typed letters are displayed.
<ul>
<li>Until the user presses the arrow keys to highlight a particular
choice, only the typed letters are displayed in the text box.</li>
<li>In an editable auto-complete, if no choices match the letter(s)
typed, the drop down list closes.</li>
<li>In a non-editable auto-complete, any letters that do not result
in a match from the list are ignored. The drop down list of choices
remains static until the user presses:
<ul>
<li><kbd>Escape</kbd> to clear the text field</li>
<li><kbd>Backspace</kbd> to remove some of the letters
previously typed</li>
<li>an additional letter that results in a valid list of
choices.</li>
</ul>
</li>
<li>Navigation through the list of choices and display of the
highlighted choice in the text box works as described above.<br>
<em> Optional: When a choice is highlighted via arrow key
navigation, the input cursor is left at the end of the typed
entry and the highlighted choice is displayed in the text box
with the characters after the input cursor selected. Typing an
additional character will remove the auto-completed portion and
append the newly typed character to the end of the previously
typed characters. The list will be filtered based on the
additional character(s) typed. </em>
</li>
</ul>
</li>
<li>With focus in a text box, press <kbd>Escape</kbd>
<ul>
<li>If there is no text in the text box, pressing <kbd>Escape</kbd>
closes the drop-down if it is displayed.
</li>
<li>For an editable autocomplete that has text in the text box that
was both typed by the user and auto-completed by highlighting a
choice using the keyboard, the auto-completed portion of the text is
cleared and the user typed characters remain in the text box. The
drop-down list is closed. To completely clear the text box contents
the user must use the backspace key to remove the typed characters.
This is how the Google search box in the Firefox UI works. <em>Recommend
that pressing the <kbd>Escape</kbd> key again completely clears
the text box rather than relying on only the backspace key.
</em>
</li>
<li>For a non-editable auto-complete that has text in the text box
that was both typed by the user and auto-completed by highlighting a
choice using the keyboard, pressing <kbd>Escape</kbd> closes the
drop-down list and leaves the current choice in the text box.
</li>
<li>For an editable or non-editable auto complete with text in the
text box that was typed by the user and the mouse is highlighting a
choice in the drop down (keyboard navigation was NOT used), pressing
<kbd>Escape</kbd> closes the drop down and leaves the typed text
displayed in the text box. Need to consider if pressing <kbd>Escape</kbd>
again should clear the typed text. The user must press the <kbd>Down</kbd>
arrow or <kbd>Alt + Down</kbd> arrow or click the associated icon to
invoke the drop-down list of choices again.
</li>
</ul>
</li>
<li>Moving focus out of an empty auto complete field where a value is
required should either invoke an error or if a default value was initially
assigned, reset the value to the default value.</li>
<li>Moving focus out of an auto complete field that does not contain a
valid entry should either invoke an error or if a default value was
initially assigned, reset the value to the default value.</li>
</ul>
<p class="note">It is good practice to limit the number of matching items in the
drop down to a reasonable number. The reasonable number is determined by the
task at hand. A list of the 50 US States is probably reasonable, but a list
containing all of the office numbers in a building is probably not appropriate.
</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The widget has a role of <a class="role-reference" href="#combobox">combobox</a>.
</li>
<li>The combobox has an <a href="#aria-autocomplete"
class="property-reference">aria-autocomplete</a> property set to one of <code>'inline'</code>,
<code>'list'</code>, or <code>'both'</code>.
</li>
<li>For more information, see the <a href="#combobox">combobox</a> design
pattern.
</li>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">Any examples referenced here that are hosted outside www.w3.org
may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be
directly incorporated into the guide.</p>
<p>
<a
href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/form/_autoComplete.html"
title="dijit.form.ComboBox Unit Test" rel="nofollow">Dojo autocomplete</a>
</p>
</section>
</section>
<section class="widget" id="combobox">
<h3>Combo Box</h3>
<p class="note">This section has not been updated since it was integrated from APG
version 1.0 -- an APG task force review is pending.</p>
<p>A combo box enables the user to type in a field and at the same time chose a
predefined value from a list. By using the keyboard the user can select an item from
the list. After selection she will be able to type further characters in the field.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Left Arrow</kbd> or <kbd>Right Arrow</kbd> move the caret within
the edit field.</li>
<li><kbd>Alt + Up/Down Arrow</kbd> opens and closes the list.</li>
<li><kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> moves focus up and down
the list. As focus moves inside the dropdown list, the edit field is
updated.</li>
<li><kbd>Page Up / Page Down</kbd> selects the next/previous pages item
depending on the lists size.</li>
<li><kbd>Escape</kbd> closes the dropdown list, returns focus to the edit
field, and does not change the current selection.</li>
<li><kbd>Enter</kbd> selects the current item on the list, updates the edit
field, highlights the selected item in the dropdown list, closes the
dropdown list, and returns focus to the input field.</li>
<li><kbd>Typing a letter (printable character) key</kbd> moves focus to the
next instance of a visible node whose title begins with that printable
letter.</li>
</ul>
<p>
For combo boxes that implement <a href="#aria-autocomplete"
class="state-reference">aria-autocomplete</a>, see the <a
href="#autocomplete">autocomplete design pattern</a>.
</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>A combobox can be implemented using either of two design patterns:</p>
<ol>
<li>As a combination of text field, which may be editable, a displayable
list of items, and a drop button to toggle the display of that list; all
wrapped in the form of a single widget with role of combobox.</li>
<li>As a combobox, which behaves like a textfield and may be editable, with
a displayable list of items, and a drop button to toggle the display of that
list;</li>
</ol>
<p>Like text fields a combobox should be labeled to convey the purpose of the
widget. Keyboard focus within the widget must be managed by the widget.
Comboboxes are used extensively in graphical user interfaces and the design
pattern for the widget should be semantically correct.</p>
<p>For the first combobox design pattern:</p>
<ul>
<li>The container element that wraps the combobox has a role of <a
href="#combobox" class="role-reference">combobox</a>.
</li>
<li>The first element within the combobox is an <code>input</code> text
field and is responsible for managing the keyboard focus between the text
field and the list as well as displaying the list. The text field is in the
tab order. If you create a text field without using a standard HTML text
field form control then ensure that it is in the tab order.
</li>
<li>If the text field is not editable it must have have <a
href="#aria-readonly" class="property-reference">aria-readonly</a> = <code>true</code>.
</li>
<li>The combobox must have <a href="#aria-expanded"
class="property-reference">aria-expanded</a> = <code>true</code> if the list
is displayed or <a href="#aria-expanded" class="property-reference">aria-expanded</a>
= <code>false</code> when it is not.
</li>
<li>The next element is an html <code><button></code>, or another
element with a role of <a href="#button" class="role-reference">button</a>.
This element is used to toggle the display of the combobox's drop down list.
</li>
<li>The next element has a <a href="#listbox" class="role-reference">listbox</a>
role and represents the drop down list. It manages keyboard navigation among
list items and navigating back to the text field if necessary.
</li>
<li>Each item in the listbox is an <a href="#option" class="role-reference">option</a>.
Options are not in the tab order.
</li>
<li>Provide a label for the combobox by referencing the text field in the
combobox. You can use an <a href="#aria-label" class="property-reference">aria-label</a>
to associate this label with the combobox or you may use the HTML <code><label></code>
element and its <code>for</code> attribute to reference the text field.
</li>
</ul>
<p>For the second combobox design pattern:</p>
<ul>
<li>The first element for the combobox has a role of combobox and behaves
like an input text field and is responsible for managing the keyboard focus
between the combobox and the list as well as displaying the list. The text
field is in the tab order. If you create a text field without using a
standard HTML text field form control then ensure that it is in the tab
order.</li>
<li>If the combobox is not editable it must have have <a
href="#aria-readonly" class="property-reference">aria-readonly</a> = <code>true</code>.
</li>
<li>The combobox must have <a href="#aria-expanded"
class="property-reference">aria-expanded</a> = <code>true</code> if the list
is displayed or <a href="#aria-expanded" class="property-reference">aria-expanded</a>
= <code>false</code> when it is not.
</li>
<li>The next element is an html <code><button></code>, or another
element with a role of <a href="#button" class="role-reference">button</a>.
This element is used to toggle the display of the combobox's drop down list.
</li>
<li>The next element has a <a href="#listbox" class="role-reference">listbox</a>
role and represents the drop down list. It manages keyboard navigation among
list items and navigating back to the text field if necessary.
</li>
<li>Each item in the listbox is an <a href="#option" class="role-reference">option</a>.
Options are not in the tab order.
</li>
<li>Provide a label for the combobox by referencing the text field in the
combobox. You can use an <a href="#aria-label" class="property-reference">aria-label</a>
to associate this label with the combobox or you may use the HTML <code><label></code>
element and its <code>for</code> attribute to reference the text field.
</li>
</ul>
<p>
For each combobox pattern the button <em>need not</em> be in the tab order <em>if</em>
there is an appropriate keystroke associated with the
<code>input</code>
element such that when focus is on the
<code>input</code>
, the keystroke triggers display of the associated drop down list. In this case,
a
<kbd>Tab</kbd>
to focus the button is unnecessary. This is the same behavior as the
<code>select</code>
element.
</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">Any examples referenced here that are hosted outside www.w3.org
may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be
directly incorporated into the guide.</p>
<p>
First design pattern -- container element with role <a href="#combobox"
class="role-reference">combobox</a>:
</p>
<ul>
<li><a href="http://www.oaa-accessibility.org/examplep/combobox5/"
title="Combobox with aria-autocomplete='inline' and role='combobox' on wrapping div"
target="_blank">Open Ajax Combobox - autocomplete='inline'</a></li>
<li><a href="http://www.oaa-accessibility.org/examplep/combobox6/"
title="Combobox with aria-autocomplete='list' and role='combobox' on wrapping div"
target="_blank">Open Ajax Combobox - autocomplete='list'</a></li>
<li><a
href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/form/_autoComplete.html?testWidget=dijit.form.ComboBox"
title="dijit.form.ComboBox Unit Test" target="_blank">Dojo/dijit nightly
build combobox</a></li>
<li><a
href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/form/_autoComplete.html?testWidget=dijit.form.FilteringSelect"
title="dijit.form.FilteringSelect Unit Test" target="_blank">Dojo
nightly build combobox with autocomplete</a></li>
</ul>
<p>
Second pattern -- text field with role <a href="#combobox"
class="role-reference">combobox</a>:
</p>
<ul>
<li><a href="http://www.oaa-accessibility.org/examplep/combobox1/"
title="Example 9 - Combobox with aria-autocomplete='none'" target="_blank">Open
Ajax Combobox - no autocomplete</a></li>
<li><a href="http://www.oaa-accessibility.org/examplep/combobox2/"
title="Combobox with aria-autocomplete='inline'" target="_blank">Open
Ajax Combobox - autocomplete='inline'</a></li>
<li><a href="http://www.oaa-accessibility.org/examplep/combobox3/"
title="Combobox with aria-autocomplete='list'" target="_blank">Open Ajax
Combobox - autocomplete='list'</a></li>
</ul>
</section>
</section>
<section class="widget" id="datepicker">
<h3>Date Picker</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>
The date picker widget allows the user to select a date or date ranges.
The date picker shows one month at least. All navigation that is described below depends on the application.
If no range selection is possible, the relevant keystroke interaction can be ignored.
Also navigation to the past might be optional.
Each week might be labeled with the corresponding calendar week number.
</p>
<p>
As a general rule the actual calendar portion of the date picker follows a table structure where days of the week and calendar day numbers are laid out in table cells.
This provides context so an assistive technology can render the day of the week; its corresponding numeric calendar day, and week number if necessary.
Consequently, it is best to start with an HTML table and apply WAI-ARIA semantics for a grid.
However, should the author wish to uses a div or span to represent the cells then the DOM structure for a table is duplicated with rows marked with <code>role="<a href="#row" class="role-reference">row</a>"</code>.
</p>
<p>The calendar portion can be displayed in a numbers of ways, including as a popup associated with another widget, or as a static region of a page.</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>Keyboard navigation on days that are not included the currently displayed month should move to the month automatically and lead to the day in the next or previous month.</p>
<ul>
<li>
<kbd>Tab</kbd> - Like other widgets, the date picker widget receives focus by tabbing into it.
Once focus is received, focus is repositioned on today's date in a grid of days and weeks.
A second tab will take the user out of the date picker widget.
Focus initially is placed on today's date.
</li>
<li>
<kbd>Shift + Tab</kbd> - reverses the direction of the tab order.
Once in the widget, a Shift+Tab will take the user to the previous focusable element in the tab order.
</li>
<li>
<kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> - goes to the same day of the week in the previous or next week respectively.
If the user advances past the end of the month they continue into the next or previous month as appropriate.
</li>
<li>
<kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> - advances one day to the next, also in a continuum.
Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks.
</li>
<li><kbd>Control + Page Up</kbd> - Moves to the same date in the previous year.</li>
<li><kbd>Control + Page Down</kbd> - Moves to the same date in the next year.</li>
<li>
<kbd>Space</kbd> -
<ul>
<li>Singleton Mode: acts as a toggle either selecting or deselecting the date.</li>
<li>
Contiguous Mode: Similar to selecting a range of text.
<kbd>Space</kbd> selects the first date.
<kbd>Shift + Arrow</kbd>s add to the selection.
Pressing <kbd>Space</kbd> again deselects the previous selections and selects the current focused date.
</li>
</ul>
</li>
<li><kbd>Home</kbd> - Moves to the first day of the current month.</li>
<li><kbd>End</kbd> - Moves to the last day of the current month.</li>
<li><kbd>Page Up</kbd> - Moves to the same date in the previous month.</li>
<li><kbd>Page Down</kbd> - Moves to the same date in the next month.</li>
<li>
<kbd>Enter</kbd> -
<ul>
<li>If the the calendar is a popup attached to some other widget (e.g., a text field), then <kbd>Enter</kbd> dismisses the popup, and the selected date(s) are shown in the associated widget.</li>
<li>If the calendar is a static region on the page, then <kbd>Enter</kbd> confirms the selected date(s).</li>
</ul>
</li>
<li><kbd>Escape</kbd> - in the case of a popup date picker, closes the widget without any action.</li>
</ul>
<p class="note">Navigation into the past is optional</p>
<p class="note">
Do not implement keyboard navigation schemes that would place more than one calendar day in the tab order at any time as this impacts the usability of keyboard navigation.
For example, using HTML anchors for the gridcells places them all in the tab order impacting the usability of keyboard navigation.
</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>
The current month has a label representing the month and year.
It is advisable to use a role <a href="#heading" class="role-reference">heading</a> but is not essential.
This "label" should have a unique ID.
</li>
<li>If the author would like to ensure that a label is announced by a screen reader, as the label changes, include live region properties with the label element: <a href="#aria-live" class="property-reference">aria-live</a><code>="assertive"</code> and <a href="#aria-atomic" class="property-reference">aria-atomic</a><code>="true"</code>.</li>
<li>The container for the day of week headers and numeric days of the week has a role of <a href="#grid" class="role-reference">grid</a>.</li>
<li>The grid has an <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> property with a value equivalent to the id of the label for the grid.</li>
<li>Each name for the day of the week has a role <a href="#columnheader" class="role-reference">columnheader</a> and is not navigable via the keyboard.</li>
<li>Each numeric day of the week has the role <a href="#gridcell" class="role-reference">gridcell</a>.</li>
<li>When a day is selected its <a href="#aria-selected" class="state-reference">aria-selected</a> is set to <code>true</code>, otherwise it is set to <code>false</code> or removed.</li>
<li>Changes in aria states, identified here, as well as focus, are clearly styled to show the user where their point of regard is and what days are selected.</li>
</ul>
<p>
When the date picker is active a calendar day of the week always has focus.
This can be achieved by setting the tabindex on that day as appropriate and then using script to give it focus.
Alternatively, the grid container could set <a href="#aria-activedescendant" class="property-reference">aria-activedescendant</a> to the id of the currently focused gridcell.
Keep in mind that older browsers may not support aria-activedescendant.
</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">
Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.
</p>
<ul>
<li><a href="http://www.oaa-accessibility.org/examplep/datepicker1/" title="" target="_blank">Open Ajax Alliance Date picker</a></li>
<li><a href="http://dojotoolkit.org/reference-guide/dijit/form/DateTextBox.html" target="_blank">Dojo/dijit</a></li>
</ul>
</section>
</section>
<section class="widget" id="dialog_nonmodal">
<h3>Dialog (Non-Modal)</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response (<a href="#dialog" class="role-reference">dialog</a>).</p>
<p>
A non-modal dialog is one which is displayed and focusable at the same time as the application which invoked it.
Also like the modal dialog, focus via the tab and shift-tab key must be maintained within the dialog.
However, a non-modal dialog should have a keyboard mechanism to return focus to the application while leaving the dialog open.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Escape</kbd> cancels the dialog without taking any action.</li>
<li><kbd>Enter</kbd> submits any data gathered in the dialog.</li>
<li><kbd>F6</kbd> is the recommended key to move focus between the application and an open non-model dialog.</li>
</ul>
<p><strong>Notes:</strong></p>
<ul>
<li>The mouse user may click on either the application or the dialog to change focus between the two.</li>
<li>In a Web application the non-modal dialog is usually always displayed above the application page, rather than in a separate browser window but that is not a requirement.</li>
<!-- Removed because drag and drop is deprecated
<li>This dialog box is draggable by the mouse user and an equivalent behavior (<a href="#draganddrop" class="design-pattern-reference">Drag & Drop</a>) should be offered to the keyboard only user.</li>
-->
<li>
Authors should take care when using <kbd>Enter</kbd> to trigger default actions since <kbd>Enter</kbd> might be connected to and trigger some other user interface element, or it might trigger the focused element.
Authors should ensure that <kbd>Enter</kbd> activates only the widget they intend.
</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p><a href="#dialog_modal">See Dialog (Modal).</a></p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">
Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.
</p>
<p><a href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/layout/tests/test_FloatingPane.html" title="dojox.layout.FloatPane - a crude non-modal Floating Window" target="_blank">Experimental dojo floating non-modal pane</a></p>
</section>
</section>
<section class="widget" id="dialog_tooltip">
<h3 > Dialog (Tooltip) </h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>A tooltip dialog is a modal dialog that is rendered near the invoking element and visually connected via a cartoon bubble-like protrusion. It is displayed when the mouse passes over or rests on that element.</p>
<section class="notoc">
<h4>Keyboard Interaction:</h4>
<ul>
<li><kbd>Escape</kbd> The tooltip dialog is closed by pressing the escape key when focus is within the dialog, mouse clicking on a close icon, or mouse clicking outside of the dialog onto the application.</li>
<li><kbd>Tab</kbd> Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.</li>
<li><kbd>Shift + Tab</kbd> Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.</li>
</ul>
<p class="note">It is modal because focus is trapped within the dialog as the user navigates via the <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> key.</p>
<p class="note">Unlike a true modal dialog, the user can click outside of the dialog, however in that case the tooltip dialog is immediately closed.</p>
<p class="note">A tooltip dialog can not be moved/dragged.</p>
<p class="note">Other than the close and move behavior, all other behaviors of a modal dialog are implemented by the tooltip dialog.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p><a href="#dialog_modal">See Dialog (Modal).</a></p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.</p>
<p><a href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/test_TooltipDialog.html" title="TooltipDialog Widget Tests" target="_blank">Dojo nightly</a></p></td>
</section>
</section>
<section class="widget" id="landmarks">
<h3>Landmark Navigation</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>Provide the appropriate landmark for the role attribute. See the <a href="#kbd_layout_landmark_XHTML">section describing landmark use</a>.</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.</p>
<ul>
<li><a href="http://juicystudio.com/article/examining-wai-aria-document-andmark-roles.php" title="Examining WAI-ARIA Document Landmark Roles" target="_blank" rel="nofollow">Juicy Studio</a> -- real world example </li>
<li><a href="http://www.oaa-accessibility.org/" title="Web Content Accessibility Guidelines 2.0 Ruleset" target="_blank" rel="nofollow">Open Ajax Alliance -- another real world example</a></li>
</ul>
</section>
</section>
<section class="widget" id="popuphelp">
<h3>Popup Help (aka Bubble Help)</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>
Popup Help contains more descriptive, or actionable, help-like text and elements.
It may contain, and was designed to handle, interactive elements such as a button, link, or text field.
It is essentially a Popup Menu with un-necessary keystrokes turned off.
The key sequence for posting Popup Help was to take advantage of F1's tie to the Help paradigm (F1 calls up application Help for example).
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Control + F1</kbd>
<ul>
<li>Posts the Popup Help widget. </li>
<li>Input focus is placed on the first interactive element in the Popup Help. </li>
<li class="note">Control F1 is used by IE to "Display a help dialog box". In IE7 and IE8 <code>event.cancelBubble=true;</code> and <code>event.returnValue=false;</code> will allow the re-purposing of keys used by the browser. In the case of IE6, you can not stop the bubble up of keys used by the browser, but can stop the bubble up to the OS. In the case of Firefox and other standard compliant browsers, <code>event.stopPropagation();</code> and <code>event.preventDefault();</code> will re-purpose the keys. </li>
<li class="note">With the exception of Control F1 to bring up Popup Help this widget is very similar to <a href="#dialog_modal">Dialog (Modal)</a> and/or <a href="#dialog_nonmodal">Dialog (Non-Modal)</a> and/or <a href="#dialog_tooltip">Dialog (tooltip)</a> described elsewhere in this document. </li>
</ul>
</li>
<li><kbd>Esc</kbd>
<ul>
<li>Causes no menu action and dismisses Popup Help. </li>
<li>Input focus is returned to the element, or widget the Popup Help was invoked from. </li>
<li>Pressing <kbd>Enter</kbd> when input focus is on the "X" glyph acts the same as pressing <kbd>Esc</kbd>. </li>
</ul>
</li>
<li><kbd>Tab</kbd>
<ul>
<li>One of the following occurs:
<ul>
<li>Modal behavior
<ul>
<li>Moves input focus between elements in the Popup Help's tabbing order.
<ul>
<li>Input focus stays in the Popup Help until one of the following occurs:
<ul>
<li><kbd>Esc</kbd> is pressed. </li>
<li><kbd>Enter</kbd> is pressed when input focus is on an interactive widget/element. </li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>Non-Modal behavior
<ul>
<li>Moves input focus to the next tabbable element in the tabbing order if the following applies:
<ul>
<li>Popup Help is posted. </li>
<li>It contains no tab navigable elements in it. </li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><kbd>Shift + Tab</kbd>
<ul>
<li>As with other keyboard conventions described here, the <kbd>Shift + Tab</kbd> has the effect of moving the focus up rather than down and follows the same conventions as described for the modal and non-modal <kbd>Tab</kbd> key above. </li>
</ul>
</li>
<li><kbd>Enter</kbd>
<ul>
<li>Activates the element in the Popup Help that has input focus, if applicable, then dismisses the popup.
<ul>
<li>Input focus should be placed on the appropriate element after the user presses the <kbd>Enter</kbd> key.
<ul>
<li>The appropriate place to move input focus to will not always be the parent element the Popup Help was invoked from. </li>
</ul>
</li>
<li>Nothing occurs if input focus is on an element that has no associated action. </li>
</ul>
</li>
</ul>
</li>
<li><kbd>F6</kbd>
<ul>
<li>In the non-modal instance, the F6 key can be used to move focus between the application and the open non-modal window. This is also the behavior described in <a href="#dialog_nonmodal">Dialog (Non-Modal)</a> above. </li>
</ul>
</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>See <a href="#dialog_modal">Dialog (Modal)</a> and/or <a href="#dialog_nonmodal">Dialog (Non-Modal)</a> and/or <a href="#dialog_tooltip">Dialog (tooltip)</a>.</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="ednote">Add link to example.</p>
</section>
</section>
<section class="widget" id="richtext">
<h3>Rich Text Editor</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>Input control that accepts free-form text as its value.</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>The edit control is provided by the browser; it provides the keyboard support for navigating, adding, removing and selecting text, so that behavior is not defined by the rich internet application. </li>
<li>The browser should also provide a keyboard mechanism for navigating into and out of the edit control. Within most browsers the edit control is put into the tab order of the page and can be navigated into, out of, and through using the tab and shift-tab keys like any standard form control. </li>
<li>A rich text editor widget needs to provide a user interface for interacting with the browser provided edit control. Interaction between the user interface and editor is defined here assuming that a toolbar is used. </li>
<li><kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> - If not provided by the browser, the rich text editor widget provides a keyboard mechanism to move into and out of the edit control. Tab and shift-tab are the recommended keystrokes. The toolbar or other user interface component associated with the editor is placed in the tab order immediately before the editor. To set an attribute on text within the edit control the user sets focus into the edit control, moves the insertion point, selects text and presses shift-tab to move focus from the editor back to the toolbar. The user navigates through the toolbar (see toolbar behavior) to a desired attribute and invokes that attribute. When an attribute is invoked, that attribute is applied to the selected text in the editor and focus moves back into the editor at the previous insertion point with the selection intact. </li>
<li><strong>Options:</strong>
<ul>
<li>Rather than using <kbd>Shift + Tab</kbd> to move focus from within the editor to the toolbar, another key combination could be used (<kbd>Alt + Up Arrow</kbd>, <kbd>Control + Shift + Letter</kbd>, etc.). This would eliminate the need to put the user interface control (in this example a toolbar) into the tab order immediately before the editor component. However, there are drawbacks to using a different keystroke to navigate to the user interface:
<ol>
<li>It is not as "discoverable" as relying on the standard <kbd>Tab/Shift + Tab</kbd> behavior; </li>
<li>It is difficult to find key combinations which are not already captured by the browser or assistive technology. </li>
<li>Focus could stay within the toolbar after the user invokes an attribute. The user would then have to press an additional key to move focus back into the editor. This would allow multiple attributes to be set on the current selection without having to return back to the user interface but it would add an extra key sequence after setting just a single attribute. Requiring a keystroke to move focus back into the editor would also require modifying the toolbar behavior to intercept this keystroke and to know how to set focus back to the component (the editor) that the toolbar is associated with. </li>
</ol>
</li>
</ul>
</li>
</ul>
<p>Optionally, if the developer wishes to provide the ability to insert a tab into the document, it is recommended one of the following methods be used. </p>
<ul>
<li>Provide indent and outdent buttons in the menu. Keyboard shortcuts to the buttons should be <kbd>Control + M</kbd> for indent and <kbd>Control + Shift + M</kbd> for outdent. </li>
<li>Provide a button in the menu to toggle the use of <kbd>Tab</kbd> between the two modes. If this button is used, then <kbd>Control + M</kbd> is recommended as a keyboard shortcut to toggle the button. </li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>Authors are advised to not use ARIA for rich text editors, but to rely on native HTML markup. Current rich text editors typically use an <code>iframe</code> element for editable content. As a result, the editable content is implicitly mapped to a document role in accessibility APIs. If using HTML5, it is recommended that authors use the <code>designMode</code> or <code>contentEditable</code> attributes.</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.</p>
<ul>
<li><a href="http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/editor/test_Editor.html" title="Editor Test" target="_blank" rel="nofollow">Dojo nightly</a>.</li>
<li><a href="http://ckeditor.com/demo" title="CKEditor demo | CKEditor.com" target="_blank" rel="nofollow">CKEditor</a>.</li>
<li><a href="http://developer.yahoo.com/yui/examples/editor/switch_editor.html" title="YUI Library Examples: Rich Text Editor: Plain Text Switcher" target="_blank" rel="nofollow">YUI Rich Text Editor</a>.</li>
</ul>
</section>
</section>
<section class="widget" id="Site_Navigator_General">
<h3>Site Navigator - General</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>
A collection of links, buttons, or tabs, usually presented in a region on the left or top of a page, that is persistent across most pages of the site.
It provides quick access to the primary sections or functions of the site.
It may also communicate the structure or hierarchy of the site, allowing the user to quickly drill down to a desired page.
It often provides orientation information similar to that of bread crumbs by indicating which page is currently displayed and what its relationship is to the other pages shown in the navigator.
Some navigators are overloaded with support for other functions, e.g., reordering pages in a wiki.
</p>
<p>
Multiple navigators may be present on a page.
For example, there may be a top-level navigator presented as tabs across the top and a second level navigator presented as sub tabs either on the top or left.
</p>
<p>
The site navigator patterns described in this guide are for interactive navigation widgets designed to help standardize solutions to accessibility requirements that have often either been ignored or implemented with other methods that are more limited in their usefulness.
For example, most site navigators implemented with static HTML provide a visual indicator of what page is currently displayed but few provide the same information programmatically.
Also, the static HTML navigators often provide information about page relationships through their visual layout that is not represented in their HTML structure.
Finally, static HTML navigators require the user to tab to every element within the navigator whereas ARIA-enabled navigators implement arrow key navigation within the navigation widget.
The navigator then becomes a single tab stop, dramatically reducing the length of the tab sequence and improving usability.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>See the <a href="#Site_Navigator_Tree">Site Navigator Tree</a> and <a href="#Site_Navigator_Tabbed_Style">Site Navigator Tabbed Style</a> sections for more detail.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>
An ARIA-enabled site navigator is made up of a container widget that enables interaction with the navigation items.
The widget is wrapped in a navigation region.
The requirements for the navigation widget, items, and region are as follows.
</p>
<ol>
<li>
Navigation container widget: the navigation items need to be contained in an appropriate widget, such as a <a class="role-reference" href="#tree">tree</a>, <a class="role-reference" href="#menubar">menubar</a>, <a class="role-reference" href="#toolbar">toolbar</a>, or <a class="role-reference" href="#listbox">listbox</a>.
See below for additional guidance on implementation using specific widget containers. If the navigator is for a hierarchical site or application, the hierarchy may be represented in one of two ways: by using a tree for the container widget or by using a separate widget for each level of the hierarchy.
If a hierarchical site or application uses a tabbed navigation construct, it will need to use one of the patterns that implements a separate widget for each level of the hierarchy.
The container widget implementation should address the following considerations and requirements.
<ol>
<li>
Label: The widget should be labelled by using <a class="property-reference" href="#aria-label">aria-label</a> or <a class="property-reference" href="#aria-labelledby">aria-labelledby</a>.
The label should briefly and adequately describe the scope of navigation.
For example, if the navigator scope is the entire site or application, the label could be set to the name of the site or application.
Labels should normally be brief, e.g., one to three words.
If multiple widgets are used to provide navigation of a hierarchy, the widget label for levels below the root widget should use <a class="property-reference" href="#aria-labelledby">aria-labelledby</a> to refer to the label of the item in the parent widget that represents the currently active navigation element.
</li>
<li>Focus management: When the widget receives focus, the item in the widget that is currently active (e.g., currently displayed) should receive the focus.</li>
<li>
<a class="property-reference" href="#aria-controls">aria-controls</a>: aria-controls should be set with a value that refers to the content region that is controlled by the navigator.
If multiple navigators are used to provide navigation of a hierarchy, navigation widgets that change the elements of a child navigator should have aria-controls set with a value that refers to the controlled child navigation widget.
</li>
<li><a class="property-reference" href="#aria-multiselectable">aria-multiselectable</a>: If the navigation widget is overloaded with non-navigation functions and if those functions can be performed on multiple elements, then the widget must support aria-multiselectable and have it set to <code>true</code>. </li>
</ol>
</li>
<li>
Navigation items: each page or content container represented in the navigator should be represented by an element, such as an <a href="#option" class="role-reference">option</a>, <a class="role-reference" href="#treeitem">treeitem</a>, <a href="#menuitemradio" class="role-reference">menuitemradio</a>, or <a class="role-reference" href="#button">button</a>.
If the navigator visually communicates which page is currently displayed, the navigation item must be able to programmatically communicate the currently displayed status using <a href="#aria-selected" class="state-reference">aria-selected</a>, <a href="#aria-checked" class="state-reference">aria-checked</a>, or <a href="#aria-pressed" class="state-reference">aria-pressed</a>.
For this reason, a navigation item may not be a link unless the link is contained inside an option or treeitem.
The states and properties of the navigation item should communicate the following.
<ol>
<li>Name of the target page or function: Every item must have an accessible name.</li>
<li>
Current display status: The item representing the page that is currently displayed should have either <a href="#aria-selected" class="state-reference">aria-selected</a> or, if it is a <a class="role-reference" href="#button">button</a>, <a href="#aria-pressed" class="state-reference">aria-pressed</a> set to <code>true</code>.
All other items in the widget must have the same state set to <code>false</code>.
If the navigation widget is overloaded with non-navigation functions and if it supports multi-selection, then <a href="#aria-checked" class="state-reference">aria-checked</a> should be used instead of <a href="#aria-selected" class="state-reference">aria-selected</a> to indicate the display status.
</li>
<li>Operational selection status: If the navigator is overloaded with non-navigation functions, each selected item must have <a href="#aria-selected" class="state-reference">aria-selected</a> set to <code>true</code> and each selectable item must have <a href="#aria-selected" class="state-reference">aria-selected</a> set to <code>false</code>.</li>
</ol>
</li>
<li>
Navigation region: Each navigation widget should be wrapped in a container with role <a class="role-reference" href="#navigation">navigation</a> and have a label that is the same as the label on the the widget.
If multiple widgets are used to support a hierarchy and if the widgets are sequential in the <kbd>Tab</kbd> order, then the navigation regions for child widgets should be nested inside the navigation region of the parent.
</li>
</ol>
<p>
The following two sections provide detailed descriptions of how to meet the above implementation requirements for site navigators using specific widgets.
The <a href="#Site_Navigator_Tree">Site Navigator Tree</a> section describes how to build a hierarchical navigator using a tree widget that contains links.
The <a href="#Site_Navigator_Tabbed_Style">Site Navigator Tabbed Style</a> section describes how to implement tabbed style site navigation using a toolbar containing toggle buttons, a menubar containing menuitemradio elements, or a listbox containing links.
These are provided as examples and are not necessarily the only implementation options that can meet all the requirements described in this section.
</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p>See the <a href="#Site_Navigator_Tree">Site Navigator Tree</a> and <a href="#Site_Navigator_Tabbed_Style">Site Navigator Tabbed Style</a> sections for examples.</p>
</section>
</section>
<section class="widget" id="Site_Navigator_Tree">
<h3>Site Navigator - Tree</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>A <a href="#Site_Navigator_General">site navigator</a> implemented using a <a class="role-reference" href="#tree">tree</a> widget that provides navigation for a hierarchical set of pages, content containers or application functions. For example, a tree-based navigator is appropriate for the typical left-hand web site navigator that has an outline-like structure where activating a link displays the target of that link in the main content area and displays the pages that are children of the current page in the navigator. Unlike the typical static left-hand navigator, a dynamic tree widget could also provide the ability for the user to explore the hierarchy of the site without having to load a parent page in order to see the titles of the children. This would improve the navigation efficiency for all users by reducing the number of page loads.</p>
<p>Some sites or applications may provide support for hierarchical navigation using tabbed style navigation by providing a tab set for each level of the hierarchy.</p>
<section class="notoc">
<h4>Keyboard Interaction: </th>
<p>The tree should implement keyboard navigation consistent with the <a href="#TreeView">Tree View design pattern</a> with one exception. When enter is pressed, the default action can be activated on any node containing a link even if it is not an end node. Note that the user can still use left and right arrow to expand and collapse nodes. Note that selection keys should not be implemented unless <a class="property-reference" href="#aria-multiselectable">aria-multiselectable</a> is <code>true</code>. If aria-multi-selectable is <code>false</code>, the default action should be to display the content associated with that item, and if possible, move the focus to the beginning of the controlled region. If aria-multiselectable is <code>true</code> and <a href="#aria-haspopup" class="property-reference">aria-haspopup</a> is <code>true</code> for the current node, then enter should open a pop-up menu that provides options for navigating to the target specified by the current node and for performing supported non-navigation operations on the currently selected items.</p>
<p>Focus: When the tree receives focus, the item in the tree that is marked as currently displayed should receive focus.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>To build a site navigator tree, build a <a class="role-reference" href="#tree">tree</a> where each <a class="role-reference" href="#treeitem">treeitem</a> contains a <a class="role-reference" href="#link">link</a>. The states and properties of the tree and tree items should be set as follows.</p>
<ul>
<li><a class="property-reference" href="#aria-label">aria-label</a> or <a class="property-reference" href="#aria-labelledby">aria-labelledby</a>: If the navigator has a visual label that briefly and adequately describes the scope of navigation, the element with role <a class="role-reference" href="#tree">tree</a> should have aria-labelledby set with a value that refers to the element containing that label. Otherwise, aria-label should be used to provide an appropriate label. See <a href="#Site_Navigator_General">Site Navigator</a> for more details on appropriate labelling of a navigation widget.</li>
<li><a class="property-reference" href="#aria-controls">aria-controls</a>: The element with role tree should have aria-controls set with a value that refers to the content region controlled by the navigator. Typically, this is the element with role <a class="role-reference" href="#main">main</a>.</li>
<li><a class="property-reference" href="#aria-multiselectable">aria-multiselectable</a>: aria-multiselectable should be set to <code>false</code> unless the navigator also provides non-navigation functions that require selection. An example of non-navigation function is the ability to re-arrange pages in a wiki.</li>
<li><a class="property-reference" href="#aria-selected">aria-selected</a>: If aria-multiselectable is <code>false</code>, the <a class="role-reference" href="#treeitem">treeitem</a> containing the link to the page or content that is currently displayed should be indicated by setting aria-selected to <code>true</code>, and all other tree items should have aria-selected set to <code>false</code>. If aria-multiselectable is <code>true</code>, then <a href="#aria-selected" class="state-reference">aria-selected</a> should be used to indicate which items are either selectable or selected for non-navigation functions.</li>
<li><a class="property-reference" href="#aria-checked">aria-checked</a>: if aria-multiselectable is <code>false</code>, aria-checked should not be specified. If aria-multiselectable is <code>true</code>, then aria-checked should be set true on the tree item containing the link to the page or content that is currently displayed, and all other tree items should have aria-checked set to <code>false</code>.</li>
<li><a class="property-reference" href="#aria-haspopup">aria-haspopup</a>: if aria-multiselectable is <code>false</code>, aria-haspopup should not be specified. If aria-multiselectable is <code>true</code>, one method for exposing non-navigation functions is to provide a pop-up menu containing those functions. If this is done, nodes that support non-navigation functions should have aria-haspopup set to <code>true</code> and the pop-up menu must also provide as its first option the default navigation function. In this way, the user can perform the navigation function simply by pressing enter twice. Or, the user can easily access non-navigation functions by pressing enter and then navigating the pop-up menu.</li>
<li>Navigation region: the tree should be wrapped in a container with role <a class="role-reference" href="#navigation">navigation</a>, which also has the same label as the tree.</li>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="ednote">Add link to example</p>
</section>
</section>
<section class="widget" id="Site_Navigator_Tabbed_Style">
<h3>Site Navigator - Tabbed Style</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>A <a href="#Site_Navigator_General">site navigator</a> that provides navigation for a small "sibling" set of pages, content containers or application functions. All the pages in the set are at the same logical level in the site navigation scheme, i.e., there are no parent/child relationships. It will often have a look and feel similar to a <a class="role-reference" href="#tabpanel">tabpanel</a>.</p>