Install & Configure

Preconfigured versions

Custom installation

To build your own implementation, download a local copy (or reference a CDN version) of a Language pack, the JS min file, and the CSS min file, and then create a new “Ed11y” instance.

For ESM/JS module imports:

Use the .umd JavaScript files for legacy browsers and systems:

Parameters

A complete implementation will only be called for logged-in editors (you don’t want your site visitors seeing your checker!), and can override any of the default parameters.

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

A heavily customized implementation might look like this:

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.

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 number and a viaJump boolean. 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 ID, as well as references to the result and tip objects. Dispatched when a tooltip appears, allowing you to modify the tips at runtime.
  • ed11yShut: provides data-ed11y-result ID. 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

Samples can be found in the following sections.

Modifying tips

If all you want to do is modify the text of a tip, items in the ed11yLang.en global (before calling the library) or Ed11y.M (after calling the library) objects can be directly overridden. e.g., in the Drupal module where we aliased the language pack to Drupal.ed11yLang:

Drupal.ed11yLang.lang.testNames.title = "Please write shorter headings."

This is true of any of the default keys in the localization file or the active language-specific translation.

The Drupal module also adds custom edit links to the tips, using the editLinks parameter. Note “Page editor” and “Layout editor:”

Tooltip with "Page editor" and "Layout editor" links inserted.

A simplified version of the code that sets that parameter:

The Drupal module then uses the ed11yPop event to dynamically show and hide the edit link based on context when tips are shown.

This event provides references to the result and tip objects:

Custom tests

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:

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:

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:

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.