README

For a comprehensive overview of Sa11y and Editoria11y, how they can assist maintaining an accessible website by supporting content editors, and to read about the rationale behind this plugin, check out the in-depth blog post at https://sebastiangreger.net/2021/11/sa11y-editoria11y-and-a-kirby-plugin or the project page at https://sebastiangreger.net/projects/a11yprompter

Overview

The A11yprompter (a11y as in accessibility, and prompter like the person assisting actors on stage) is a tiny wrapper to easily add a user-friendly automatic content accessibility checker to the frontend of a website built with Kirby CMS.

The plugin currently integrates both Editoria11y and Sa11y, and even allows to try them both at random. They are specifically developed to assist content editors to not break a site's accessibility as they create content; not full-fledged accessibility validators, but tools that nudge editors to follow a11y guidelines.

In addition, Bookmarklet Accessibility Audit Tool BAAT (more oriented towards professional auditors) or legacy tool Tota11y can be configured to be used for specific purposes (not suitable for non-technical content editors in day-to-day productive use).

Installation

Download and copy this repository to /site/plugins/kirby-a11yprompter

Or use Composer:

composer require sgkirby/a11yprompter

Or install as Git submodule

git submodule add https://codeberg.org/sebastiangreger/kirby-a11yprompter site/plugins/kirby-a11yprompter

Setup

There is only one step needed to get started. Add the following to the template or snippet rendering the end of your HTML body (like site/snippets/footer.php in the Kirby Starterkit, for example), just before the closing </body> tag:

<?= snippet('a11yprompter') ?>

This will render the required <script> and <style> tags to include the checker tool in the page; by default, one of the two tools is chosen at random – think of it as a kind of "tryout" mode (while pretty similar, both tools have different UI and feature sets, so this might be handy to find your preferred solution).

The tool is only displayed when loading a web page as a logged-in user – careful if Kirby's built-in page cache is in use; you may want to disable page caching for logged-in users.

You should now be ready to go – make sure you are logged in to your Kirby website and open any page on the frontend that is rendered using the template/snippet with this code.

Configuration

Additional configuration variables can be included in the snippet call to customize the setup. The $data variable is expected to be an associative array, as with any other Kirby snippet:

<?= snippet('a11yprompter', $data) ?>

Checker engine selection

To turn off the randomized "tryout" mode and permanently settle for one engine, set the engine value accordingly:

Value	Description
`'engine' => 'sa11y'`	Uses Sa11y
`'engine' => 'editoria11y'`	Uses Editoria11y
`'engine' => 'random'` or empty (default)	Randomly loads either Sa11y or Editoria11y on every page load, good for finding the most suitable tool or to compare results
`'engine' => 'baat'`	Uses BAAT; this is never shown when using the `random` option due to its more specialized target audience and since this is likely used temporarily for accessibility testing during development
`'engine' => 'tota11y'`	Uses Tota11y; this "forebear" of the newer solutions, not updated since 2019, is only included here for reference purposes or very specific use cases, it is never shown when using the `random` option as its target audience is different from the others

So, to only use Sa11y, set:

<?= snippet('a11yprompter', ['engine' => 'sa11y']) ?>

NB. Both engine names do not contain L letters, but numeric characters 1.

Template limitation

By default, the checker tool is shown on every page that contains the template with this snippet. To limit, you may hand an array of template names to the snippet:

Value	Description
`templates` => array	An array of template IDs that will include the checker tool, e.g. `'templates' => ['article']`

Access control

By default, the checker tool is shown to every logged-in user. You can limit this further by setting one of the following arrays in the $data variable:

Value	Description
`'users' =>` array	An array of user IDs that will see the checker tool, e.g. `'users' => ['ascd1234', 'b2cy82t5']`
`'roles' =>` array	An array of user roles that will see the checker tool, e.g. `'roles' => ['admin']`

For example, a complete setup with template and access limitations could look like this:

<?= snippet('a11yprompter', [
  'engine'    => 'sa11y',
  'templates' => ['article', 'note'],
  'roles'     => ['admin', 'leadeditor'],
]) ?>

Script parameters

To override selected default settings of the checker scripts, overwrite them using an array named after the tools' name:

Value	Description
`sa11y` => array	An array of properties for the Sa11y tool; see https://sa11y.netlify.app/developers/props/
`editoria11y` => array	An array of parameters for the Editoria11y tool; see https://editoria11y.princeton.edu/configuration/#parameters

For example, to change the Editoria11y variable alertMode from its default value of polite to assertive, use the following code:

<?= snippet('a11yprompter', [
  'engine'      => 'editoria11y',
  'editoria11y' => [
    'alertMode' => 'assertive',
  ],
]) ?>

Or, to override the Sa11y default prop checkRoot (the DOM scope the checker examines) from its default value of body to main, use:

<?= snippet('a11yprompter', [
  'engine' => 'sa11y',
  'sa11y'  => [
    'checkRoot' => 'main',
  ],
]) ?>

Take a look at the various config variables of both scripts – they each enable a great (but different) amount of customization, from including/excluding certain areas to other interface settings.

Probably the most important setting is the limitation of the tested area to a specific DOM element (e.g. to only target the area that can be edited by authors, not the rest of page, usually rendered from fixed templates); default is the entire body:

Sa11y	Editoria11y
`'checkRoot' => '#content'`	`'checkRoots' => '#content'` (comma-separated for multiple)

Credits

This plugin is merely a little helper to easily embed the Editoria11y and Sa11y tools into websites built with Kirby 3. My original contribution is limited to making them available by use of a Kirby snippet in a template.

Editoria11y is maintained by John Jameson and is provided to the community thanks to the Digital Accessibility initiatives at Princeton University's Office of Web Development Services. It started as a fork of Sa11y created by Digital Media Projects, Computing and Communication Services (CCS) at Ryerson University in Toronto, Canada and lead and maintained by Adam Chaboryk, which has since evolved into version 2. Sa11y itself began as a fork of Tota11y by Khan Academy, and uses FontAwesome icons and jQuery. BAAT is developed by Mindscreen GmbH and runs the axe-core testing engine by Deque Systems, Inc.

License

Kirby A11yprompter is open-sourced software licensed under the GPLv2 license, to comply with the original GPLv2 license of Editoria11y. Sa11y, Tota11y and BAAT are licensed under the MIT license, and axe-core under Mozilla Public License 2.0, both permitting their inclusion in GPLv2-licensed software. The included version of BAAT has been altered to load the axe-core validator locally rather than from a CDN.

It is discouraged to use this plugin in any project that promotes the destruction of our planet, racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.

sgkirby / a11yprompter

Maintainers

Details