{"id":330,"date":"2018-12-10T16:35:40","date_gmt":"2018-12-10T16:35:40","guid":{"rendered":"https:\/\/pressbooks.library.ryerson.ca\/wafd\/?post_type=chapter&#038;p=330"},"modified":"2022-12-16T17:04:16","modified_gmt":"2022-12-16T17:04:16","slug":"suggestion-boxes","status":"publish","type":"chapter","link":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/chapter\/suggestion-boxes\/","title":{"raw":"Suggestion Boxes","rendered":"Suggestion Boxes"},"content":{"raw":"A suggestion box (aka, combo box or autocomplete box) is a type of selection menu that helps users enter a correct choice. They are typically made up of a text entry field and a list of choices based on a number of characters entered into the text field. In the example provided here, entering a few characters brings up a list of countries that contain those characters.\r\n\r\nBecause the text entry field is a standard form text input field, it will be accessible by default. No additional coding is required to make it accessible. What needs the most attention is the list of choices, which needs to announce itself when it appears and needs to be keyboard navigable.\r\n<div class=\"textbox\">\r\n\r\n<strong>WAI-ARIA roles, states, and properties used in a suggestion box<\/strong>\r\n<ul>\r\n \t<li>role='region'<\/li>\r\n \t<li>aria-live='polite'<\/li>\r\n \t<li>aria-describedby='[id of instructions div]'<\/li>\r\n<\/ul>\r\n<\/div>\r\n<div style=\"margin: 1em 0; padding: 1em; border: 1px solid #ddd; border-left: 10px solid #0000ff;\"><strong>Suggested Reading:<\/strong> For details on constructing accessible suggestion boxes, refer to: <a class=\"external\" href=\"https:\/\/www.w3.org\/WAI\/ARIA\/apg\/patterns\/combobox\/\" target=\"_blank\" rel=\"noopener noreferrer\">ARIA Authoring Practices Guide: Combo Box<\/a>.<\/div>\r\nThe following JSFiddle presents a typical suggestion box. Review the JavaScript and HTML markup, and test the suggestion box presented under the Result tab with ChromeVox to understand how it functions without any accessibility features added. You can work in JSFiddle itself by clicking \"Edit in JSFiddle\", copying the accessibility\/WAI-ARIA code described below to fix the accessibility of the suggestion box, before completing\u00a0<a href=\"https:\/\/pressbooks.library.torontomu.ca\/wafd\/chapter\/4-4-activity-5-accessible-suggestion-box\/\">Activity 5<\/a>, on the page that follows.\r\n<div style=\"height: 600px; overflow: hidden;\">[h5p id=\"21\"]<\/div>\r\nDefine some instructions to make it clear there will be suggestions appearing when text is entered into the text input field.\r\n<div style=\"height: 215px; overflow: hidden;\">[h5p id=\"22\"]<\/div>\r\nWhen the suggestion box receives focus, generate the instructions for it by adding the <code>notify()<\/code> function to the <code>onFocus()<\/code> function to produce a live region with the instruction text.\u00a0 This instruction text is then read automatically when a screen reader encounters the suggestion box text field.\r\n<div style=\"height: 140px;\">[h5p id=\"23\"]<\/div>\r\nWithin the <code>init()<\/code> function, create a <code>&lt;div&gt;<\/code> to use as a live region, adding <code>aria-live=\"polite\"<\/code> to announce the list usage instructions defined above when the text field receives focus. Also, give it a <code>role=\"region\"<\/code> so it can be found in the landmarks list.\r\n<div style=\"height: 140px;\">[h5p id=\"24\"]<\/div>\r\nProvide additional instructions when the suggestion box is populated, adding to the <code>getSuggestions()<\/code> function.\r\n<div style=\"height: 110px;\">[h5p id=\"25\"]<\/div>\r\n<h2>Adding Keyboard Operability<\/h2>\r\nWAI-ARIA best practices defines all recommended suggestion box keyboard functionality, listed below. In our example, only the required keyboard events are included.\r\n<div class=\"textbox\">\r\n<h3>Suggestion Box Keyboard Interaction<\/h3>\r\nWhen focus is in the textbox:\r\n<ul>\r\n \t<li>Down Arrow: If the popup is available, moves focus into the popup:\r\n<ul>\r\n \t<li>If the autocomplete behaviour automatically selected a suggestion before Down Arrow was pressed, focus is placed on the suggestion following the automatically selected suggestion.<\/li>\r\n \t<li>Otherwise, places focus on the first focusable element in the popup.<\/li>\r\n<\/ul>\r\n<\/li>\r\n \t<li>Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.<\/li>\r\n \t<li>Esc: Dismisses the popup if it is visible. Optionally, clears the textbox.<\/li>\r\n \t<li>Enter: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the textbox so the user can add another recipient.<\/li>\r\n \t<li>Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.<\/li>\r\n \t<li>Standard single line text editing keys appropriate for the device platform (see note below).<\/li>\r\n \t<li>Alt+Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.<\/li>\r\n \t<li>Alt+Up Arrow (Optional): If the popup is displayed:\r\n<ul>\r\n \t<li>If the popup contains focus, returns focus to the textbox.<\/li>\r\n \t<li>Closes the popup.<\/li>\r\n<\/ul>\r\n<\/li>\r\n<\/ul>\r\n<div style=\"margin: 1em 0; padding: 1em; border: 1px solid #ddd; border-left: 10px solid #3c3;\">\r\n\r\n<strong>Note:<\/strong>\u00a0Standard single line text editing keys appropriate for the device platform:\r\n<ol>\r\n \t<li>include keys for input, cursor movement, selection, and text manipulation.<\/li>\r\n \t<li>Standard key assignments for editing functions depend on the device operating system.<\/li>\r\n \t<li>The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the <code>contenteditable<\/code> HTML attribute.<\/li>\r\n \t<li><strong>IMPORTANT:<\/strong> Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.<\/li>\r\n<\/ol>\r\n<\/div>\r\n<p style=\"text-align: left;\"><a href=\"https:\/\/www.w3.org\/WAI\/ARIA\/apg\/patterns\/combobox\/#keyboard-interaction-6\">Source: W3C ARIA Authoring Practices Guide<\/a><\/p>\r\n\r\n<\/div>\r\nThe most significant effort in making the suggestion box accessible is adding keyboard operability. In our case, we\u2019ll add Up and Down Arrow operability to the list box. Create a switch that captures the keypress event. If it\u2019s a Down Arrow, select the next item down in the list. If it\u2019s an Up Arrow, select the previous item. If it\u2019s any character key, enter the value in the text field. Add this to the <code>onKeyUp()<\/code> function, while integrating the existing functionality in the function into the default for the switch statement.\r\n<div style=\"height: 820px; overflow: hidden;\">[h5p id=\"26\"]<\/div>\r\n<h2>Accessible Suggestion Box in Action<\/h2>\r\nWatch the following video to see how ChromeVox interacts with a suggestion box. When the suggestion box receives focus, instructions are read. When the second letter is typed into the text field a list of suggestions appears below. Additional instructions are provided on how to make a selection from the list. Arrow keys are used to navigate through the suggestions, and the Enter key is used to select one of them. Aim to have the suggestion box you update in <a href=\"https:\/\/pressbooks.library.ryerson.ca\/wafd\/chapter\/4-4-activity-5-accessible-suggestion-box\/\">Activity 5<\/a> on the following page operate and announce like the one in the video.\r\n\r\n<strong>Video: <a href=\"https:\/\/www.youtube.com\/watch?v=IGqaH8HrIu0\" rel=\"noopener\">Accessible Suggest Box<\/a><\/strong>\r\n\r\n[embed]https:\/\/www.youtube.com\/embed\/IGqaH8HrIu0[\/embed]","rendered":"<p>A suggestion box (aka, combo box or autocomplete box) is a type of selection menu that helps users enter a correct choice. They are typically made up of a text entry field and a list of choices based on a number of characters entered into the text field. In the example provided here, entering a few characters brings up a list of countries that contain those characters.<\/p>\n<p>Because the text entry field is a standard form text input field, it will be accessible by default. No additional coding is required to make it accessible. What needs the most attention is the list of choices, which needs to announce itself when it appears and needs to be keyboard navigable.<\/p>\n<div class=\"textbox\">\n<p><strong>WAI-ARIA roles, states, and properties used in a suggestion box<\/strong><\/p>\n<ul>\n<li>role=&#8217;region&#8217;<\/li>\n<li>aria-live=&#8217;polite&#8217;<\/li>\n<li>aria-describedby='[id of instructions div]&#8217;<\/li>\n<\/ul>\n<\/div>\n<div style=\"margin: 1em 0; padding: 1em; border: 1px solid #ddd; border-left: 10px solid #0000ff;\"><strong>Suggested Reading:<\/strong> For details on constructing accessible suggestion boxes, refer to: <a class=\"external\" href=\"https:\/\/www.w3.org\/WAI\/ARIA\/apg\/patterns\/combobox\/\" target=\"_blank\" rel=\"noopener noreferrer\">ARIA Authoring Practices Guide: Combo Box<\/a>.<\/div>\n<p>The following JSFiddle presents a typical suggestion box. Review the JavaScript and HTML markup, and test the suggestion box presented under the Result tab with ChromeVox to understand how it functions without any accessibility features added. You can work in JSFiddle itself by clicking &#8220;Edit in JSFiddle&#8221;, copying the accessibility\/WAI-ARIA code described below to fix the accessibility of the suggestion box, before completing\u00a0<a href=\"https:\/\/pressbooks.library.torontomu.ca\/wafd\/chapter\/4-4-activity-5-accessible-suggestion-box\/\">Activity 5<\/a>, on the page that follows.<\/p>\n<div style=\"height: 600px; overflow: hidden;\">\n<div id=\"h5p-21\">\n<div class=\"h5p-content\" data-content-id=\"21\"><\/div>\n<\/div>\n<\/div>\n<p>Define some instructions to make it clear there will be suggestions appearing when text is entered into the text input field.<\/p>\n<div style=\"height: 215px; overflow: hidden;\">\n<div id=\"h5p-22\">\n<div class=\"h5p-content\" data-content-id=\"22\"><\/div>\n<\/div>\n<\/div>\n<p>When the suggestion box receives focus, generate the instructions for it by adding the <code>notify()<\/code> function to the <code>onFocus()<\/code> function to produce a live region with the instruction text.\u00a0 This instruction text is then read automatically when a screen reader encounters the suggestion box text field.<\/p>\n<div style=\"height: 140px;\">\n<div id=\"h5p-23\">\n<div class=\"h5p-content\" data-content-id=\"23\"><\/div>\n<\/div>\n<\/div>\n<p>Within the <code>init()<\/code> function, create a <code>&lt;div&gt;<\/code> to use as a live region, adding <code>aria-live=\"polite\"<\/code> to announce the list usage instructions defined above when the text field receives focus. Also, give it a <code>role=\"region\"<\/code> so it can be found in the landmarks list.<\/p>\n<div style=\"height: 140px;\">\n<div id=\"h5p-24\">\n<div class=\"h5p-content\" data-content-id=\"24\"><\/div>\n<\/div>\n<\/div>\n<p>Provide additional instructions when the suggestion box is populated, adding to the <code>getSuggestions()<\/code> function.<\/p>\n<div style=\"height: 110px;\">\n<div id=\"h5p-25\">\n<div class=\"h5p-content\" data-content-id=\"25\"><\/div>\n<\/div>\n<\/div>\n<h2>Adding Keyboard Operability<\/h2>\n<p>WAI-ARIA best practices defines all recommended suggestion box keyboard functionality, listed below. In our example, only the required keyboard events are included.<\/p>\n<div class=\"textbox\">\n<h3>Suggestion Box Keyboard Interaction<\/h3>\n<p>When focus is in the textbox:<\/p>\n<ul>\n<li>Down Arrow: If the popup is available, moves focus into the popup:\n<ul>\n<li>If the autocomplete behaviour automatically selected a suggestion before Down Arrow was pressed, focus is placed on the suggestion following the automatically selected suggestion.<\/li>\n<li>Otherwise, places focus on the first focusable element in the popup.<\/li>\n<\/ul>\n<\/li>\n<li>Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.<\/li>\n<li>Esc: Dismisses the popup if it is visible. Optionally, clears the textbox.<\/li>\n<li>Enter: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the textbox so the user can add another recipient.<\/li>\n<li>Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.<\/li>\n<li>Standard single line text editing keys appropriate for the device platform (see note below).<\/li>\n<li>Alt+Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.<\/li>\n<li>Alt+Up Arrow (Optional): If the popup is displayed:\n<ul>\n<li>If the popup contains focus, returns focus to the textbox.<\/li>\n<li>Closes the popup.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<div style=\"margin: 1em 0; padding: 1em; border: 1px solid #ddd; border-left: 10px solid #3c3;\">\n<p><strong>Note:<\/strong>\u00a0Standard single line text editing keys appropriate for the device platform:<\/p>\n<ol>\n<li>include keys for input, cursor movement, selection, and text manipulation.<\/li>\n<li>Standard key assignments for editing functions depend on the device operating system.<\/li>\n<li>The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the <code>contenteditable<\/code> HTML attribute.<\/li>\n<li><strong>IMPORTANT:<\/strong> Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.<\/li>\n<\/ol>\n<\/div>\n<p style=\"text-align: left;\"><a href=\"https:\/\/www.w3.org\/WAI\/ARIA\/apg\/patterns\/combobox\/#keyboard-interaction-6\">Source: W3C ARIA Authoring Practices Guide<\/a><\/p>\n<\/div>\n<p>The most significant effort in making the suggestion box accessible is adding keyboard operability. In our case, we\u2019ll add Up and Down Arrow operability to the list box. Create a switch that captures the keypress event. If it\u2019s a Down Arrow, select the next item down in the list. If it\u2019s an Up Arrow, select the previous item. If it\u2019s any character key, enter the value in the text field. Add this to the <code>onKeyUp()<\/code> function, while integrating the existing functionality in the function into the default for the switch statement.<\/p>\n<div style=\"height: 820px; overflow: hidden;\">\n<div id=\"h5p-26\">\n<div class=\"h5p-content\" data-content-id=\"26\"><\/div>\n<\/div>\n<\/div>\n<h2>Accessible Suggestion Box in Action<\/h2>\n<p>Watch the following video to see how ChromeVox interacts with a suggestion box. When the suggestion box receives focus, instructions are read. When the second letter is typed into the text field a list of suggestions appears below. Additional instructions are provided on how to make a selection from the list. Arrow keys are used to navigate through the suggestions, and the Enter key is used to select one of them. Aim to have the suggestion box you update in <a href=\"https:\/\/pressbooks.library.ryerson.ca\/wafd\/chapter\/4-4-activity-5-accessible-suggestion-box\/\">Activity 5<\/a> on the following page operate and announce like the one in the video.<\/p>\n<p><strong>Video: <a href=\"https:\/\/www.youtube.com\/watch?v=IGqaH8HrIu0\" rel=\"noopener\">Accessible Suggest Box<\/a><\/strong><\/p>\n<p><iframe loading=\"lazy\" id=\"oembed-1\" title=\"Accessible Suggest Box\" width=\"500\" height=\"281\" src=\"https:\/\/www.youtube.com\/embed\/IGqaH8HrIu0?feature=oembed&#38;rel=0\" frameborder=\"0\" allowfullscreen=\"allowfullscreen\"><\/iframe><\/p>\n","protected":false},"author":100,"menu_order":3,"template":"","meta":{"pb_show_title":"on","pb_short_title":"","pb_subtitle":"","pb_authors":[],"pb_section_license":""},"chapter-type":[],"contributor":[],"license":[],"class_list":["post-330","chapter","type-chapter","status-publish","hentry"],"part":33,"_links":{"self":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapters\/330","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapters"}],"about":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/wp\/v2\/types\/chapter"}],"author":[{"embeddable":true,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/wp\/v2\/users\/100"}],"version-history":[{"count":97,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapters\/330\/revisions"}],"predecessor-version":[{"id":2004,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapters\/330\/revisions\/2004"}],"part":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/parts\/33"}],"metadata":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapters\/330\/metadata\/"}],"wp:attachment":[{"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/wp\/v2\/media?parent=330"}],"wp:term":[{"taxonomy":"chapter-type","embeddable":true,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/pressbooks\/v2\/chapter-type?post=330"},{"taxonomy":"contributor","embeddable":true,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/wp\/v2\/contributor?post=330"},{"taxonomy":"license","embeddable":true,"href":"https:\/\/pressbooks.library.torontomu.ca\/wafd\/wp-json\/wp\/v2\/license?post=330"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}