Using Aria role=dialog to expose a custom dialog (pop-up div box)

From WCAG WG

Status

Editorial note

The title of this technique is just a draft - it may become just an example in a more encompassing technique (e.g., Using ARIA role=dialog).

User Agent Notes

Screen reader support is decent on desktop, still patchy in mobile OSs and browsers (iOS/Safari/VoiceOver, Android/Firefox/Talkback)

Win 7, IE 9, JAWS 14: supported
Win 7, FF 18, JAWS 14: not supported
Win 7, IE9, NVDA 2012.2.1 supported
Win 7, FF 18, NVDA 2012.2.1: supported
Mac OS 10.8.X, Safari, VoiceOver: supported
iOS 6.1,Safari, VoiceOver (iPad mini): partial support (does not annoince role dialog, but the dialog heading associated via aria-labelledby)
Android 4.2, Firefox, Talkback (Nexus 7): partial support (dialog is announced, but only after closing the dialog)

Full testing results at Using Aria role=dialog (optimised for mobile browsers), now also tested with NVDA 2012.3.1

Applicability

As of this writing this technique applies to HTML technologies.

This technique relates to:

1.3.1 Info and Relationships, Situation B

Description

Authors often use JavaScript to insert custom modal dialogues (usually divs) instead of opening a new browser window. The ARIA role dialog allows authors to assign a dialogue role to make screen reader users aware of the custom dialogue element inserted (or made visible via CSS).

For screen reader users, it is vital that the script also manages the focus to make users aware of the modal dialogue. Scripts can

move the keyboard focus from the triggering element (link or button) to the custom dialogue (or one of the focussable elements within it)
keep it within the custom dialogue (this makes the dialogue effectively modal)
move it back to the triggering element when the user closes the dialogue by activating one of the choices offered.

Examples

Example 1: A link opens a custom dialogue

A link on the page ("Display a dialogue") displays a small custom dialog with a text ("Just an example") and two buttons, "OK" and "Cancel". In the example below, the script merely shows a hidden div. More frequently, the dialogue will be inserted into the page via AJAX / DOM scripting.

<p><a onclick="toggleDialog('show');" href="#">Display a dialog</a></p>

<div tabindex="-1" style="display: none;" role="dialog" aria-labelledby="myDialog" id="box" class="box-hidden">
	<h3 id="myDialog">Just an example.</h3>
	<button onclick="toggleDialog('hide');" class="close-button">OK</button>
	<button onclick="toggleDialog('hide');" class="close-button">Cancel</button>		
</div>

Style and Script in <head> section of page:

<style>
.box-hidden {
	display: none;
	position: absolute;
	top: 19em; left:15em; width:20em; height:5em;
	border: 2px solid black;
	padding:0 1em 1em 1em;
	background-color: #eee;
	z-index:1002;
	overflow: auto;
	}		
</style>

<script>
var dialogOpen = false, lastFocus, dialog, okbutton, pagebackground;

function showDialog(el) {
	lastFocus = el || document.activeElement;
	toggleDialog('show');
}
function hideDialog(el) {
	toggleDialog('hide');
}

function toggleDialog(sh) {
	dialog = document.getElementById("box");
	okbutton = document.getElementById("ok");
	pagebackground = document.getElementById("bg");

	if (sh == "show") {
		dialogOpen = true;

		// show the dialog 
		dialog.style.display = 'block';
		
		// after displaying the dialog, focus an element inside it
		okbutton.focus();
		
		// only hide the background *after* you've moved focus out of the content that will be "hidden"
		pagebackground.setAttribute("aria-hidden","true");
		
	} else {
		dialogOpen = false;
		dialog.style.display = 'none';
		pagebackground.setAttribute("aria-hidden","false");
		lastFocus.focus(); 
	}
}


document.addEventListener("focus", function(event) {

    var d = document.getElementById("box");

    if (dialogOpen && !d.contains(event.target)) {
        event.stopPropagation();
        d.focus();
    }

}, true);


document.addEventListener("keydown", function(event) {
    if (dialogOpen && event.keyCode == 27) {
        toggleDialog('hide');
    }
}, true);

</script>

Look at script of custom dialog (code only)

Resources

WAI ARIA 1.0 Authoring Practices
Making an accessible dialog box by Nicholas C. Zakas
Custom-Built Dialogs by Gez Lemon

Related Techniques

Tests

Procedure

For elements that use ARIA role=dialog

Check that role=dialog is used as attribute of the container (such as a div) that is used as custom dialog and inserted (or made visible) via JavaScript following a user interaction or some other event
Check that for any dialog element that is present on the page but not displayed, the element has an aria-hidden attribute set to false as a default.
Check that for any dialog element that is displayed following user interaction, its aria-hidden attribute set to true.
Check that when closing the dialog element, its aria-hidden attribute is set back to false.

Expected Results

Test #1, test #2, test #3 and test #4 are true.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.