Configuration

On this page:

Turnkey installs

If installation on the site is not possible, try the Sa11y bookmarklet.

Vanilla JS installs

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

<link href="/PATH/TO/YOUR/COPY/OR/CDN/editoria11y.min.css" rel="stylesheet">

<script src="/PATH/TO/YOUR/COPY/OR/CDN/editoria11y.min.js"></script>

<script>
  const ed11y = new Ed11y({
    // options would go here
  });           
</script>

Note that Editoria11y will be looking for that CSS file link tag to copy it into the various shadow DOM components. If you aggregate CSS in your implementation, you MUST provide a URL to an un-aggregated copy, by adding the URL to the cssUrls array:

<script src="/PATH/TO/YOUR/COPY/editoria11y.min.js"></script>
<script>
  const ed11y = new Ed11y({
    cssUrls: ["/PATH/TO/YOUR/COPY/editoria11y.min.css"]
  });           
</script>

Parameters

A complete implementation will only be called for logged-in editors (you don’t want your site visitors seeing your checker!), and may have custom parameters.

Note that defaults are provided for all parameters; only include things you want to override.

A heavily customized implementation might look like this:

<script src="/PATH/TO/YOUR/editoria11y.min.js"></script>
<script>
  const ed11y = new Ed11y({
    
    // Define content regions
    checkRoots: 'main, .footer-content-zone',

    // Add custom CSS file
    cssUrls: [
      '/css/editoria11y.min.css', 
      '/css/custom.css'
    ],
      
    // Define Web components to include in checks
    shadowComponents: 'accordion, lightbox',
      
    // We want the box to open automatically for errors:
    alertMode: 'assertive',
      
    // Our external link icon has 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',
      
    // Prevent this user from hiding alerts.
    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,
      
    // Dispatch a JS event before highlighting this,
    // so our JS can modify it first:
    hiddenHandlers: ".accordion-panel",
      
    // Dispatch a JS event when the library is ready
    // for custom tests, then wait for 3 ed11yResume  
    // events from our 3 tests to continue.
    customTests: 3,

  });
</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.

Theming

Several parameters allow for selecting a theme, overriding colors, and injecting CSS.

Only include the parameters you need to override to make future updates easier.

// Add custom CSS file
cssUrls: ['/css/editoria11y.min.css', '/css/custom.css'],

theme : 'darkTheme', // Select base theme
darkTheme: {         // Override base colors
    bg: '#0a2051',
    bgHighlight: '#7b1919',
    text: '#f4f7ff',
    primary: '#4930a0',
    primaryText: '#f4f7ff',
    secondary: '#20160c',
    warning: '#fad859',
    alert: '#b80519',
    button: '#dde8ff',
    focusRing: 'cyan',
    activeTab: '#0a2051',
    tipHeader: '#4930a0',
},

// Override fonts
baseFontSize: 14, // px
baseFontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif',

Useful JS events

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

In typical order of appearing…

  • ed11yRunCustomTests: dispatched when the Results object is ready for custom results to be injected. Note that the customTests parameter must be set to the number of custom test functions you will be running (…probably one…) for this event to dispatch. Details in following section.
  • ed11yResults: dispatched when all checks are finished. API integrations can now harvest data out of the Ed11y.results object.
  • 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 following sections.

Custom tests

As of 2.1.0, if the customTests parameter is a number, Editoria11y will dispatch an “ed11yRunCustomTests” event while checking, and then pause for up to 500ms while listening for that number of “ed11yResume” events.

This can be leveraged to call as many scripts containing custom tests as you like, which can push their results into the results array before the tips are draws.

For example, if you wanted to create this tip, to flag links that have been pasted from emails with obfuscated URLs:

Tip reading "URL is Safe Link Encoded"

You would:

  1. Add a listener for the ed11yRunCustomTests event
  2. Find matching elements
  3. Define the tip message
  4. Dispatch the “resume” event to let Editoria11y draw the tip:
document.addEventListener('ed11yRunCustomTests', function() {

  // 1. Write your custom test. This can be anything you want.
  //
  // This example searches the page using the Ed11y.findElements() function, 
  // which is aware of the checkRoots and ignoreElements parameters. 
  // It adds an array key for 'safeLinks', based on a CSS selector. 

  Ed11y.findElements('safeLinks','a[href*="safelinks.protection.outlook.com/?"]');


  // This is just a utility function for this particular test...
  const decodeSafelink = function(url) {
      const params = new URL(url).searchParams;
      let decoded = params.get('url');
      if (!!decoded) {
            decoded = Ed11y.sanitizeForHTML(decoded);
            return `<p>The actual URL may be:<br><em style='word-wrap: break-word;'>${decoded}</em></p>`
      }
      return '';
  }


  // 2. Create the content for your tip.

  // Add a key to the Ed11y.M translation object:
  Ed11y.M.outlookSafeLink = {
 
     // Provide a title and a body:
 
     title: 'URL is Safe Link encoded',
      tip: (href) => 
          `<p>The URL for this link has been copied from an email. 
              It includes the original recipient email address, 
              and will bounce all clicks through the Outlook Safelinks server.</p>
          <p>The specified URL is:<br>
          <em style='word-break: break-all;font-size:90%;line-height: 1.2;display: block;'>
             ${Ed11y.sanitizeForHTML(href)}
          </em></p>
          ${decodeSafelink(href)}
          `,
  };

  // 3. Push each item you want flagged to Ed11y.results.
  // 
  // You must provide:
  //   el:           The element itself
  //   test:         A key for your test, created in step 2.
  //   content:      The tip you created above.
  //   position:     "beforebegin" for images and links, 
  //                 "afterbegin" for paragraphs.
  //   dismissalKey: false for errors, 
  //                 a unique string for manual checks.
  
  Ed11y.elements.safeLinks?.forEach((el) => {
      Ed11y.results.push({
          element: el,
          test: 'outlookSafeLink',
          content: Ed11y.M.outlookSafeLink.tip(el.getAttribute('href')),
          position: 'beforebegin',
          dismissalKey: false,
      })
  })

  // 4. When you are done with all your custom tests, dispatch an "ed11yResume" event:

  let allDone = new CustomEvent('ed11yResume');
  document.dispatchEvent(allDone);

})

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.