Examples

axe-tools is built as both an ES module and a Universal module (umd). As a result it is able to integrate with all web applications. It has special support for Vue apps through a plugin, but it will also examine the DOM on any page. You can import the library through an import statement or a <script> tag. Review the examples below to get started.

HTML

<script src="https://tools.ais.its.uiowa.edu/axe-tools/axe-tools.umd.js"></script>
<script>
    //console.log('AXE TOOLS CONFIG', axeTools)
    
    axeTools.setPageRoute('${play.mvc.Router.route(request).path}')
    //console.log('Page Route', axeTools.getPageRoute())
    
    axeTools.registerAxeReporter({
        appName: 'Campus Data',
        teamName: 'Ent-Apps',
        logReport: true,
        timeout: 5000
    })
</script>

For applications that use a traditional request/response page model, the library can be imported with a <script> tag. This example pulls the latest version of the library. Developers can also pin usage to a specific version by using the path /versions/axe-tools/{x.y.z}/axe-tools.umd.js. The library's API is exposed through the global variable axeTools. Typically, these scripts are imported on an application's site template(s) although they can be added on a page-by-page basis as needed.

The first call to setPageRoute() is optional. It communicates the parameterized route to Axe Tools. This example is from a Play application, and we use the Play router to access the parameterized route.

The second call, registerAxeReporter() does all the heavy lifting to configure axe-tools. It will create all the necessary event listeners to scan the page after the specified timeout and after any DOM changes. See the options for details on configuration.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Vue 3

// main.ts
import {AxeToolsPlugin, resolveEnvironment} from '@ais-public/axe-tools'
// ...

const app = createApp(App)
//...

app.use(AxeToolsPlugin, {
  appName: 'axe-tools-example',
  teamName: 'ent-apps',
  logReport: true,
  baseUrl: 'http://localhost:5173',
  env: resolveEnvironment(),
  router: router
})

app.mount('#app')

Axe Tools supports Vue applications by exposing the plugin AxeToolsPlugin. It is installed using Vue's standard use() method.

Note the execution environment is determined with a call to resolveEnvironment(). Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Finally, we provide the Vue router to the plugin. This allows the plugin to automatically use parameterized route paths to collect related errors in a single bucket.

Nuxt 3

// {nuxt-root}/plugins/axe-tools.client.ts
import {AxeToolsPlugin, resolveEnvironment} from "@ais-public/axe-tools"
import type {AxeToolsOptions, Env} from "@ais-public/axe-tools"
import {useRouter} from "#imports";

export default defineNuxtPlugin((nuxtApp) => {

  const router = useRouter()
  let env: Env = resolveEnvironment("profiles.uiowa.edu");

  nuxtApp.vueApp.use(AxeToolsPlugin, {
    appName: 'Profiles',
    teamName: 'Ent-Apps',
    logReport: env !== 'PROD',
    baseUrl: origin,
    timeout: 5000,
    router: router,
    env: env
  } as AxeToolsOptions)
})

AxeToolsPlugin can be used in a Nuxt application by creating a client-only Nuxt plugin. Create a file axe-tools.client.ts in your /plugins directory. You can access the Vue application via the nuxtApp object. Nuxt will automatically load the plugin on startup.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Vue 2

// App.vue
<script>
import {AxeReporter, resolveEnvironment } from '@ais-public/axe-tools';
import router from "./router";

export default {
  
  data: () => ({
    axeReporter: null,
    timeout: 5000,
    timeoutID: 0,
    isProdLaunch: false,
  }),
  
  created() {

      this.axeReporter = new AxeReporter(
        'elements-of-success', 
        'ESS', 
        true, 
        'https://test.its.uiowa.edu/elements-of-success',
        resolveEnvironment()
      );

      document.addEventListener('visibilitychange', () => {
        if (document.hidden) {
          const transmitSuccess = this.axeReporter.transmitMinimumResults();
          if (!transmitSuccess) {
            console.error('There was a problem transmitting accessibility telemetry');
          }
        }
      });
  },

  mounted() {
    // gets the most specific route path matched by the current route
    const currentRoutePath = router.currentRoute.matched.length > 0 ? router.currentRoute.matched[router.currentRoute.matched.length - 1].path : undefined;

    window.clearTimeout(this.timeoutID);
    this.timeoutID = window.setTimeout(() => this.axeReporter.scan(currentRoutePath), this.timeout);
  }
}
</script>

With a Vue 2 application, configuration is more manual. Developers can create the AxeReporter object in the application component (typically App.vue) on the created() event. The axe scan will be scheduled on the mounted() event.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

baseUrl

If the host application is not running at the root of its domain, you will need to set axe-tools' baseUrl attribute to correctly collect results in the backend. That is your application is deployed at a url like apps.its.uiowa.edu/dispatch instead of events.uiowa.edu. You can dynamically compute the baseUrl using the site's origin plus base path, or you could provide a manual mapping based on all your deployment environments. Here is how NPP computes its baseUrl.

export default defineNuxtPlugin((nuxtApp) => {
  let env: Env = resolveEnvironment("apps.ais.its.uiowa.edu/npp");
  const router = useRouter();

  // Origin will evaluate to:
  // - localhost:3000
  // - test.ais.its.uiowa.edu
  // - apps.ais.its.uiowa.edu
  const origin = typeof window !== 'undefined' ? window.location.origin : '';
  
  // Will resolve to something like:
  // - apps.ais.its.uiowa.edu/npp
  const baseUrl = origin + '/npp';

  nuxtApp.vueApp.use(AxeToolsPlugin, {
    appName: 'NPP',
    teamName: 'Ent-Apps',
    baseUrl: baseUrl,
    router: router,
    env: env,
    logReport: env !== 'PROD'
  } as AxeToolsOptions);
});