ARIA Popups

Expected behaviors

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

The 4X ARIA Popup 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 Popup module:

  • role=region
  • aria-labelledby
  • aria-expanded

Available attributes for the triggering element:

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

HTML syntax

Triggering Element


<button id="popupTriggerId"> MORE INFO </button>

To ensure the greatest level of accessibility, a triggering element should always consist of a native button or link.

Popup Container


<div hidden id="popupId">
  <button aria-label="Close" class="CloseDC"><!-- Close Icon Here --></button>
  <div> Popup 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 popup 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 myPopupDC = $A.setPopup( "#popupTriggerId", {
  // Configure functionality key / value mappings
});

Parameters

  1. A DOM element or CSS selector to specify the triggering element
  2. A configuration map to customize behaviors and options

Configuration


{

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

// Specify the role name for the popup that will be conveyed to screen reader users. E.G. "Movie Details"
role: "Popup Purpose",

// Optionally specify the popup 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.
content: "#popupId",

// Optionally specify the popup 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: "#popupId"
}
},

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

// Optionally specify if the popup is an alert message.
// If true, a system alert will be fired when the popup is rendered.
isAlert: false,

// Optionally toggle the hidden attribute instead of inserting the popup content when rendered.
    toggleHide: false,

// Preload markup in the background when using the Fetch API to load external content.
preload: true,

// Preload images in the background when using the Fetch API to load external content.
preloadImages: true,

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

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

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

// Optionally specify a timeout length in milliseconds, after which the popup 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 popup.
// 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/Popups" 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.setPopup() function.

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

// Close the popup manually.
myPopupDC.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"