ARIA Dialogs

Expected behaviors

Move focus into the dialog when it is rendered, ensure that the background content is hidden from screen reader users, ensure that the beginning and ending boundaries are conveyed to screen reader users, make sure the dialog can be closed from the keyboard, ensure that circular tabbing confines keyboard focus within the dialog content, and move focus back to the triggering element after the dialog is removed.

The 4X ARIA Dialog module automatically configures all required ARIA attributes and focus handling, in strict accordance with the ARIA specification.

The following attributes are handled automatically by the Dialog module:

  • role=dialog/alertdialog
  • aria-label
  • aria-hidden
  • inert

Available attributes for the triggering element:

  • data-controls : The resource path and pointer to the ID attribute of the dialog container element. May consist of a traditional id reference within the same document, or a url+id reference for pulling a dialog in from an external resource. E.G. data-controls="path/get.php?type=login#dialogContainerId"

HTML syntax

Triggering Element (Optional)


<button id="dialogTriggerId"> SIGN-IN </button>

To ensure the greatest level of accessibility, a triggering element should always consist of a native button or link. However, it is not necessary to have a triggering element to create a new dialog.

Dialog Container


<div hidden id="dialogId">
  <button aria-label="Close" class="CloseDC"><!-- Close Icon Here --></button>
  <div> Dialog content... </div>
</div>

When Implementing a Close link or button, the className must match the "closeClassName" property within the script declaration. Doing so will automatically bind the close methods with this element, and set keyboard focus properly when the dialog is closed. If closeClassName is not specified, the default class will be set to "CloseDC" instead. The aria-label attribute provides an informative name for non-sighted screen reader users no matter what the visible icon is set to.

JavaScript syntax


var myDialogDC = $A.setDialog( domNodeOrCSSSelector, {
// Configure functionality key / value mappings
});

Parameters

  1. A DOM node or CSS selector to specify either the dialog container element or the dialog triggering element. If referencing a triggering element, the data-controls attribute can be used to specify the id of the associated dialog container.
  2. A configuration map to customize behaviors and options

Configuration


{

// Unique ID for the dialog instance
id: "UniqueId",

// Specify the role name for the dialog that will be conveyed to screen reader users.
role: "Dialog Purpose",

// Specify the dialog triggering element if applicable.
// Not necessary if already specified in the first parameter of the $A.setDialog() function.
trigger: "#dialogTriggerId",

// Optionally specify the dialog container element within the same document.
// May be a DOM node or CSS selector.
// Not necessary if data-controls is set on the triggering element or if already specified in the first parameter of the $A.setDialog() function.
content: "#dialogId",

// Optionally specify the dialog to be rendered when referencing external content.
// Not necessary if data-controls is set on the triggering element.
// If set, the content property will be auto-populated with the returned content.
fetch: {
url: "path/file.htm",
data: {
selector: "#dialogId"
}
},

// Set the class name for the top level container element
className: 'dialog',

// Set the class name for the close button.
// This must match the class name for any close links or buttons within the dialog content, which will cause close event binding to automatically occur when the content is rendered.
closeClassName: "CloseDC",

// Optionally specify if the dialog is an alert message.
// If true, a system alert will be fired when the dialog is rendered that will instantly convey the dialog content to screen reader users.
isAlert: false,

// Specify if the dialog is a modal dialog.
isModal: true,

// Optionally run a script after the dialog finishes rendering.
afterRender: function(DC) {
// DC.container includes the rendered dialog content.
},

// Optionally run a script after the dialog is removed.
afterRemove: function(DC) {
// Do something.
},

// Optionally specify a delay in milliseconds to wait before rendering the dialog after the triggering element is activated.
delay: 0,

// Optionally specify a timeout length in milliseconds, after which the dialog will automatically close.
delayTimeout: 0,

// Optionally override the default timeout function that occurs after the delayTimeout length is reached.
timeout: function(dc) {
dc.remove();
},

// Optionally specify a render and remove animation effect for the dialog.
// Requires the "Animate" module import to function, which is powered by Velocity.js.
// To ignore animation effects, delete the animate object declaration entirely from the setup script.
// View implementations within "Templates/Dialogs" for practical animation usage examples.

style: { display: "none" }, // Set the initial state to hidden in prep for animation.

animate: {

onRender: function(dc, wrapper, next) {

// Specify the render animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for rendering.
}
});

},

onRemove: function(dc, wrapper, next) {

// Specify the removal animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for removal.
}
});

}

}

// Additional DC API properties and methods can be declared here also to customize functionality and behavior.
// To view available options, reference the help docs located at: "Help/DC API/DC Object Configuration"

}

Programmatic control


// Use the DC object that is returned by the $A.setDialog() function.

// Open the dialog manually.
myDialogDC.render(function() {
  // Optionally do something after rendering completes.
});

// Close the dialog manually.
myDialogDC.remove(function() {
  // Optionally do something after removal completes.
});

// Additional DC API properties and methods can be applied here as well.
// To view available options, reference the help docs located at: "Help/DC API/DC Object Properties and Methods"