Configuration

Turnkey installs

DIY installs

To build your own implementation, download a local copy (or reference a CDN version) of “editoria11y.min.js,” and then create a new “Ed11y” instance:

<script src="/PATH/TO/YOUR/COPY/editoria11y.min.js"></script>
  <script>
    const ed11y = new Ed11y({
      // options,
    });           
  </script>

Customization

A complete implementation will only be called for logged-in editors (you don’t want your site visitors seeing your checker!) and will have set various custom options. It might look more like this:

<script src="/PATH/TO/YOUR/COPY/editoria11y.min.js"></script>
  <script>
    const ed11y = new Ed11y({
      // We have two content regions
      checkRoots: 'main, .footer-content-zone',
      
      // We have two custom shadow components
      shadowComponents: 'accordion-widget, lightbox-widget',
      
      // We want the box to open automatically for errors:
      alertMode: 'assertive',
      
      // We wanted to pick our own colors:
      theme : 'darkTheme',
      darkTheme: {
          bg: '#0a2051',
          bgHighlight: '#7b1919',
          text: '#f4f7ff',
          primary: '#4930a0',
          primaryText: '#f4f7ff',
          secondary: '#20160c',
          warning: '#fad859',
          alert: '#b80519',
          button: '#dde8ff',
          focusRing: 'cyan',
          activeTab: '#0a2051',
          tipHeader: '#4930a0',
      },
      
      // We have an external link icon with visually hidden text
      // to delete before checking if the link has text:
      linkIgnoreStrings: ['(opens in new window)'],
      
      // Content editors cannot edit these elements:
      ignoreElements: 'nav *, #social-block',
      
      // We don't want to ignore alerts, only fix or mark OK:
      allowHide: false,
      allowOK: true,
      
      // Don't scan while the editor toolbar is open:
      doNotRun : ".editor-toolbar",

      // If a tooltip is being drawn on an element 
      // that might be invisible, warn the user first:
      checkVisible: true,
      
      // Send a JS event when highlighting tips in this element,
      // so our own JS can open the accordion and show it:
      hiddenHandlers: ".accordion-panel",
    });
  </script>

Turnkey integrations often set these variables on the fly – e.g., loading pages in “assertive” mode when they were recently edited, and switching back to “polite” after several minutes.

Useful JS events

Themers can hook these events to react and modify the page as needed.

In typical order of appearing…

  • ed11yResults: dispatched when a check finishes. API integrations can now harvest data out of the Ed11y.results array.
  • ed11yPanelOpened: dispatched if the panel opens, automatically or manually.
  • ed11yShowHidden: provides a data-ed11y-result value. Only dispatched if the “ed11yShowHidden” parameter is set and the a parent of the element matches a selector . Used to reveal alerts in not-yet-open containers, e.g., accordions, tabs and carousels. Usage examples in next section.
  • ed11yPop: provides data-ed11y-result value. Dispatched when a tooltip appears.
  • ed11yShut: provides data-ed11y-result value. Dispatched when a tooltip closes.
  • ed11yDismissalUpdate: provides extended information when a user dismisses or restores an alert. Used for API integrations. Event object contains:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Code samples can be found in the next section.

Dealing with alerts on hidden or size-constrained content

Many interactive components (tabs, sliders, accordions) hide content. The Editoria11y info panel includes next/previous buttons to jump directly to issues. If Editoria11y thinks the issue’s tooltip is currently invisible, it will alert the user something is wrong, and then highlight the first visible ancestor – e.g., the div around an accordion.

Ideally, your theme will make those elements visible before Editoria11y’s visibility check runs, so everything just works like magic for your users — carousels auto-advance and accordions auto-open to display the issue.

To do this when the panel first opens (e.g., unfolding all accordion panels with issues) add a JS event listener for ed11yPanelOpened, then do a querySelectorAll for relevant ed11y-element-result elements, and then trigger whatever function your theme uses to reveal that part of the page.

Here’s a jQuery based example. When the panel opens, it disables a sticky menu (so elements are not covered), then looks for any ed11y-element-result elements inside closed accordion items and simulates a click on their toggle button:

document.addEventListener("ed11yPanelOpened", function () {
  $('body').addClass('no-stick');
  $('ed11y-element-result').each(function () {
    if ($(this).parents('.ps-accordion-content[style*="display"]').length > 0) {
    $(this).parents('.ps-accordion-content').prev().find('.ps-accordion-item-button').click();
    }
})

To reveal content only when jumping to a specific tip via the panel’s “next” button (e.g., in a closed tab or the next carousel slide), you will need to set both hiddenHandlers to relevant CSS selectors and checkVisible to TRUE in your parameters. Then add an event listener for the ed11yShowHidden event. This is thrown if Editoria11y recognizes a tip is inside a container with one of the listed hiddenHandlers selectors provided in the options list. This JS event will include the ID of the tip that it is about to open. Editoria11y will then pause briefly after dispatching this event, to give your JS time to make the element visible.

Here’s an example from a Penn State implementation. It looks for the element matching the provided ID, then finds its parent interactive component container, and triggers its event to activate its toggle:

context.addEventListener('ed11yShowHidden', e => {
  context.getElementById(e.detail.id)
    .closest('[data-interactive-component]')
    .dispatchEvent(new CustomEvent('component:activate'));
});

Last note: some themes are just not compatible with visibility checking — e.g., the <main> container has a height of 0px. Such sites should disable all visibility checking by setting checkVisible to false.