Turnkey installs
- Editoria11y Drupal Module
- Editoria11y WordPress Plugin
- Editoria11y SquareSpace Injector (Requires Commerce/Business tier)
If installation on the site is not possible, Sa11y has a bookmarklet version.
DIY 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/editoria11y.min.css" rel="stylesheet">
<script src="/PATH/TO/YOUR/COPY/editoria11y.min.js"></script>
<script>
const ed11y = new Ed11y({
// options,
});
</script>
Note that Editoria11y will be looking for that CSS file, to copy it into the various shadow DOM components. If you aggregate CSS in your implementation, you MUST provide a direct URL to a copy of an that file as well, by setting a cssUrls parameter:
<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/COPY/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-widget, lightbox-widget',
// We want the box to open automatically for errors:
alertMode: 'assertive',
// 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",
// Send a JS event when the library is ready for custom tests,
// Then wait for three ed11yResume events 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-resultvalue. 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-resultvalue. Dispatched when a tooltip appears. - ed11yShut: provides
data-ed11y-resultvalue. 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 to 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 run as many custom tests as you like, and then push the results into the results array.
Here’s a simple script with one check, for links with a particular string in their HREF. It adds a listener for the ed11yRunCustomTests event, finds matching elements, defines the tip message, and dispatches the resume event:
document.addEventListener('ed11yRunCustomTests', function() {
// 1. Write your custom test.
// This can be anything you want.
//
// This example uses Ed11y.findElements(),
// which respects checkRoots and ignoreElements,
// to find links with a particular string in their URL.
Ed11y.findElements('safeLinks','a[href*="safelinks.protection.outlook.com/?"]');
// 2. Create a message for your tooltip.
// You'll need a title and some contents,
// as a value for the key you create for your test.
//
// Be sure to use the same key as the test name below.
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 '';
}
Ed11y.M.outlookSafeLink = {
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's 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
// test: A key for your test
// 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);
})
This example would produce a tip like this:
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.