Widget: Dialog

Example


Details

Implementing This Widget

Implementing the Dialog widget is done when you want to have a dialog box that can receive and return keyboard focus for keyboard users, and that will also be optimized for being described properly to screen reader users. Because there are so many options available for dialog popups, most of the configuration for this is driven by the javascript.

Prerequisites:

Before you begin, you must first create a div with an unique ID, and if you want to use the default style, the dialog class.

To implement the Dialog widget:

  1. In your javascript, invoke the function initializeAlertDialog and pass it the ID of the div you created.

    2. This will return a function that you can call, which takes two arguments: the trigger element (which is what receives focus when the dialog is closed), and a set of configuration parameters.

  2. Call the returned function with the following two arguments:
    1. triggerElement: The element that was activated in order to show the dialog box.
    2. config: An object with the following fields:
      • message: This is the text that you want your dialog box to contain. You can either invoke this with a string or with an HTML node (in case you want to use a form or control rendering).
      • title: This is the title, or label, for the dialog box. It's a normal string.
      • describedby: This is an optional field containing the ID of an existing element that describes the dialog box. It'll be set via aria-describedby. If both describedby and description are set, the behavior for description will override and describedby will be ignored.
      • description: This is an optional field used to set text for aria-describedby for screenreaders. Set this to a string value and that string will be added to a visually hidden paragraph within the dialog box, and the dialog box will reference it as a descriptor.
      • wrapperID: This is the ID of the wrapper div that contains the bulk of your website. If present, the element with this ID is set to aria-hidden=true when the dialog is shown, and aria-hidden=false when the dialog is dismissed. It's considered best practice to use this approach - if you don't provide a wrapper ID, you must use custom lifecycle functions in order to disable access to the rest of your page while the dialog box is visible.
      • lifecycle: This is an optional object used to specify a set of lifecycle functions. You can specify up to four such functions by using the following keys in the lifecycle object:
        • preOpen: This function will fire immediately before the dialog box is rendered.
        • postOpen: This function will fire immediately after the dialog box is rendered.
        • preClose: This function will fire immediately before the dialog box is closed.
        • postClose: This function will fire immediately after the dialog box is closed.
    3. buttons: This is an array of button configurations. The buttons specified here will be attached to the buttonbar at the bottom of the dialog box. All buttons specified here will automatially close the dialog window - but you can use the button-specific preClose and postClose functions described below to trigger custom behavior that's bound to a specific button. A button configuration has the following properties:
      • either label or markup - if you just want the widget to draw a standard button and you just want to label it, provide the label. Alternatively, provide html markup describing the button you want (So an example label might be "Continue", while example markup might be <button id="myButtonID"> Some Text</button> ).
      • Optional preClose and postClose functions. preClose here will run as soon as the button is clicked, before the dialog box's primary preClose lifecycle function; postClose here will run after the whole thing is closed, after the dialog box's primary postClose lifecylce function. Use these to define custom behaviors attached to specific buttons.
      • An optional handleEscape: true field will ensure that pressing escape simulates clicking this button. Don't have more than one per dialog window - the first one will be used, and additional ones ignored.
    4. showHeader: A boolean argument which determines whether the dialog's title is shown. According to the spec, a dialog may choose to include a header element which contains the label (and the dialog box points to it via aria-labelledby). If the header is not included, the label is attached directly to the dialog via aria-label.
    5. isAlert: This is an optional boolean flag that will set the dialog's role to alertdialog if true.
    6. isMessage: This is an optional boolean flag that specifies that the alert dialog's content is more than a simple message. For more details, see Description category details. If this boolean is true, then when the dialog opens the content area gets the initial focus, rather than the first button. This is always true for non-alert dialogs.

Expected Operation and Accessibility Features

The dialog box should be able to be used to achieve the same result whether the interaction is with a mouse or keyboard, and whether used by a sighted or screen reader user.

This covers the dialog widget and the alertdialog widget. With a little bit more tweaking it will work for the non-modal dialog widget as well.

Validation and Developer Notes

In order to validate this control, you must test manually with screen reader software, a mouse, and a keyboard. Depending on your unique configuration, all user interface elements within the dialog must be tested for proper focus and any custom behavior functionality.

Notes for the Developer:

You have to keep a reference to the triggerElement activated to show the dialog box so that you can return focus to it after the dialog is closed.

This was written so that you never have to add more than one dialog box to your application. Since they are modal you will never have more than one up at a time. As a result you can keep your HTML relatively clean and push all of your configuration into the javascript. That way, every time you show this dialog box you tell it all the details it needs in order to render itself correctly. If you DO want more than one (for example, for styling purposes) you can still do that without conflict.

Example Implementation Reference

To view an implementation of this widget, see Dialog widget example.