All Examples: Add browser and assistive technology support notice (pull

#1404) Modifies examples/js/examples.js to add a disclosure at the top of every example page with notices regarding limitations of the example. Reminds readers to test before using, use simple HTML where possible, and refers to the aria-at project for information about future support tables. Co-authored-by: Zoë Bijl <5457769+ZoeBijl@users.noreply.github.com> Co-authored-by: Zoë Bijl <zoe.bijl@crowdstrike.com> Co-authored-by: Simon Pieters <zcorpan@gmail.com> Co-authored-by: JaEun Jemma Ku <a11ydoer@gmail.com> Co-authored-by: Valerie Young <valerie@bocoup.com> Co-authored-by: Matt King <a11ythinker@gmail.com>
w3c · Jun 30, 2020 · 162a945 · 162a945
1 parent 3909695
commit 162a945
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 0 deletions.
diff --git a/examples/js/app.js b/examples/js/app.js
@@ -2,4 +2,60 @@
 (function () {
   // Load syntax highlighting
   hljs.initHighlightingOnLoad();
+
+  // Add support notice to all examples
+  window.addEventListener('DOMContentLoaded', addSupportNotice, false);
+
+  function addSupportNotice() {
+    // The "Example" heading
+    var headings = document.querySelectorAll('h2');
+    var foundExampleHeading;
+    for (var i = 0; i < headings.length; ++i) {
+      if (headings[i].textContent.trim().match(/^Examples?$/)) {
+        foundExampleHeading = true;
+        break;
+      }
+    }
+    if (!foundExampleHeading) {
+      return;
+    }
+
+    // The #browser_and_AT_support link
+    var supportLink = document.querySelector('a[href$="#browser_and_AT_support"]');
+    if (!supportLink) {
+      return;
+    }
+
+    // Get the right relative URL to the root aria-practices page
+    var urlPrefix = supportLink.getAttribute('href').split('#')[0];
+
+    // Expected outcome '../js/app.js' OR '../../js/app.js'
+    var scriptSource = document.querySelector('[src$="app.js"]').getAttribute('src');
+    // Replace 'app.js' part with 'notice.html'
+
+    var fetchSource = scriptSource.replace('app.js', './notice.html');
+    //fetch('https://raw.githack.com/w3c/aria-practices/1228-support-notice/examples/js/notice.html')
+    fetch(fetchSource)
+    .then(function(response) {
+      // Return notice.html as text
+      return response.text();
+    })
+    .then(function(html) {
+      // Parse response as text/html
+      var parser = new DOMParser();
+      return parser.parseFromString(html, "text/html");
+    })
+    .then(function(doc) {
+      // Get the details element from the parsed response
+      var noticeElement = doc.querySelector('details');
+      // Rewrite links with the right urlPrefix
+      var links = doc.querySelectorAll('a[href^="/#"]');
+      for (var i = 0; i < links.length; ++i) {
+        links[i].pathname = urlPrefix;
+      }
+      // Insert the support notice before the page's h1
+      var heading = document.querySelector('h1');
+      heading.parentNode.insertBefore(noticeElement, heading.nextSibling);
+    })
+  }
 }());
diff --git a/examples/js/notice.html b/examples/js/notice.html
@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>support notice (template)</title>
+<details id="support-notice" class="note">
+    <summary>Important Note About Use of This Example</summary>
+    <p>
+        Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.
+    </p>
+    <ul>
+    <li>
+        There may be support gaps in some
+        <a href="/#browser_and_AT_support">browser and assistive technology combinations</a>,
+        especially for <a href="/#mobile_and_touch_support">mobile/touch devices</a>.
+        Testing code based on this example with assistive technologies is essential before considering use in production systems.
+    </li>
+    <li>
+        The <a href="https://github.com/w3c/aria-at/">ARIA-AT project</a>
+        plans to provide measurements of this example's assistive technology support by the end of 2020.
+    </li>
+    <li>
+        Robust accessibility can be further optimized by choosing implementation patterns that
+        <a href="https://www.w3.org/TR/using-aria/#rule1">maximize use of semantic HTML</a>
+        and heeding the warning that
+        <a href="/#no_aria_better_bad_aria">No ARIA is better than Bad ARIA</a>.
+    </li>
+    </ul>
+</details>