Skip to content

Commit

Permalink
Feed Example: Complete Documentation
Browse files Browse the repository at this point in the history 
For issue #246, modified examples/feed/feed.html:
* Completed description.
* Completed keyboard documentation
* Completed roles, states, and properties documentation* Completed links to javascript and css files
* Updated HTML source section
* Added link to review issue.

Also deleted unused file examples/feed/css/feed.css.
  • Loading branch information
@mcking65
mcking65 committed Dec 7, 2017
1 parent 5ba0012 commit 346556b
Show file tree
Hide file tree
Showing 2 changed files with 106 additions and 69 deletions.
4 changes: 0 additions & 4 deletions examples/feed/css/feed.css
View file

This file was deleted.

171 changes: 106 additions & 65 deletions examples/feed/feed.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,24 @@
<script src="../js/examples.js"></script>
<script src="../js/highlight.pack.js"></script>
<script src="../js/app.js"></script>

<!-- js and css for this example. -->
<link href="css/feed.css" rel="stylesheet">
<script src="js/feed.js" type="text/javascript"></script>
</head>
<body>
<main>
<h1>Feed Example</h1>
<p>
<strong>NOTE:</strong> This page is work in progress; is not ready for review.
Work on this example is tracked by
<a href="https://github.com/w3c/aria-practices/issues/246">issue 246.</a>
<strong>NOTE:</strong> Please provide feedback on this example in
<a href="https://github.com/w3c/aria-practices/issues/565">issue 565.</a>
</p>
<p>
The example below implements the
<a href="../../#feed">feed design pattern.</a>
for a restaurant review site.
To immitate an infinitely scrolling set of data, information about ten restaurants is repeated infinitely.
To immitate an infinitely scrolling set of data, information about ten restaurants is repeatedly loaded as the user reads the feed.
Outside of the feed, an article load time selector is available for simulating data fetch delays.
</p>
<p>
Unlike other examples in the WAI-ARIA Authoring Practices, the example experience has its own page separate from this documentation page.
</p>
<section>
<h2 id="ex_label">Example</h2>
<div role="separator" id="ex_start_sep" aria-labelledby="ex_start_sep ex_label" aria-label="Start of"></div>
Expand All @@ -42,18 +40,6 @@ <h2 id="ex_label">Example</h2>
<div role="separator" id="ex_end_sep" aria-labelledby="ex_end_sep ex_label" aria-label="End of"></div>
</section>

<section>
<h2>Accessibility Features</h2>
<p class="annotate">Optional section: If appropriate, please replace this content with a list of any special or noteworthy accessibility features
demonstrated in this implementation, such as:</p>
<ol>
<li>What distinguishes this example from related examples.</li>
<li>Keyboard chortcuts, live regions, unusual event handling, or other ancillary best practices that are employed.</li>
<li>Do not include information that would be repeated in the following keyboard and attribute sections.</li>
<li>Delete this section if not needed.</li>
</ol>
</section>

<section>
<h2 id="kbd_label">Keyboard Support</h2>
<table aria-labelledby="kbd_label" class="def">
Expand All @@ -65,31 +51,27 @@ <h2 id="kbd_label">Keyboard Support</h2>
</thead>
<tbody>
<tr>
<th><kbd>KeyName</kbd></th>
<td>
Description of key function.
<!-- Do not use a list if there is only one function for the key. -->
</td>
<th><kbd>Page Down</kbd></th>
<td>Move focus to next article.</td>
</tr>
<tr>
<th><kbd>KeyName</kbd></th>
<td>
<ul>
<li>If condition 1, performs function 1.</li>
<li>If condition 2, performs function 2.</li>
<li>Only use a list if multiple statements are needed.</li>
</ul>
</td>
<th><kbd>Page Up</kbd></th>
<td>Move focus to previous article.</td>
</tr>
<tr>
<th><kbd>Control + End</kbd></th>
<td>Move focus to the first focusable element after the feed.</td>
</tr>
<tr>
<th><kbd>Control + Home</kbd></th>
<td>Move focus to the first focusable element before the feed.</td>
</tr>
</tbody>
</table>
</section>

<section>
<h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
<!--
Update this table to describe how roles, properties, states, and tabindex are used in this example.
-->
<table aria-labelledby="rps_label" class="data attributes">
<thead>
<tr>
Expand All @@ -101,61 +83,120 @@ <h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
</thead>
<tbody>
<tr>
<th scope="row"><code>RoleName</code></th>
<td><!-- Leave this cell blank in rows where a role is being described. --></td>
<td><code>HTML_ELEMENT</code></td>
<th scope="row"><code>feed</code></th>
<td></td>
<td><code>div</code></td>
<td>
<ul>
<li>Identifies the element that contains the set of feed articles.</li>
<li>The feed element is a structural container that it is not focusable.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>aria-labelledby="IDREF"</code></th>
<td><code>div</code></td>
<td>Provides an accessible name for the feed element.</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>aria-busy="true"</code></th>
<td><code>div</code></td>
<td>
<ul>
<li>Set during the process of loading additional articles.</li>
<li>Removed when the article load process is complete.</li>
<li>Enables assistive technologies to ignore DOM changes during the load process and then render the changes when the DOM is stable.</li>
</ul>
</td>
</tr>
<tr>
<th scope="row"><code>article</code></th>
<td></td>
<td><code>div</code></td>
<td>
Describe usage/purpose, e.g., indicates the focusable element that serves as the ...
<ul>
<li>Identifies an element that contains content for a feed article.</li>
<li>Feed articles and their content are Dynamically created in the JavaScript.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>tabindex="0"</code></th>
<td><code>div</code></td>
<td>
<!-- Leave this cell blank in rows that describe attributes applied to the element with the previously described role.
Make a row like this for each attribute/value pair.
-->
<ul>
<li>Makes the article element focusable and includes it in the page <kbd>Tab</kbd> sequence.</li>
<li>As the user reads, the feed loads additional articles based on either focus position or scroll position.</li>
<li>Assistive technologies can ensure new articles are loaded and correctly visually positioned by ensuring that the article containing the assistive technology reading cursor has or contains DOM focus.</li>
</ul>
</td>
<th scope="row"><code>AttributeName=<q>AttributeValue</q></code></th>
<td><code>HTML_ELEMENT</code></td>
</tr>
<tr>
<td> </td>
<th scope="row"><code>aria-labelledby="IDREF_LIST"</code></th>
<td><code>div</code></td>
<td>
<ul>
<li>explanation of usage, purpose, benefit, and/or guidance relevant to this implementation.</li>
<li>If making multiple statements, use list for brevity and clarity</li>
<li>Do not make a single item list.</li>
<li>Identifies one or more elements in the article that provide a distinguishing label.</li>
<li>In this example, the restaurant name sufficiently identifies each article.</li>
<li>Note: due to the nature of feeds, labels are often not unique.</li>
</ul>
</td>
</tr>
<tr>
<td> </td>
<th scope="row"><code>aria-describedby="IDREF_LIST"</code></th>
<td><code>div</code></td>
<td>
<ul>
<li>Refers to the list of elements that provide the main content of the article.</li>
<li>Does not include elements that are identically repeated in every article, e.g., does not include the &quot;Bookmark&quot; button.</li>
<li>Enables assistive technology users to skim the feed.</li>
</ul>
</td>
</tr>
<tr>
<td> </td>
<th scope="row"><code>aria-posinset="INTEGER"</code></th>
<td><code>div</code></td>
<td>
<ul>
<li>Indicates the position of the article in the feed.</li>
<li>Numbering starts with 1.</li>
<li>Note: If articles are added to the beginning of the feed, all articles are renumbered.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>aria-setsize="INTEGER"</code></th>
<td><code>div</code></td>
<td>Set to the total number of articles currently contained by the feed element.</td>
</tr>
</tbody>
</table>
</section>

<section>
<h2>Javascript and CSS Source Code</h2>
<!-- After the js and css files are named with the name of this example, change the href and text of the following 2 links to refer to the appropriate js and css files. -->
<p>The following Javascript and CSS is used by the feedDisplay.html page:</p>
<ul>
<li>
CSS:
<a href="css/feed.css" type="tex/css">feed.css</a>
</li>
<li>
Javascript:
<a href="js/feed.js" type="text/javascript">feed.js</a>
</li>
<li><a href="css/feedDisplay.css" type="tex/css">feedDisplay.css</a></li>
<li>Javascript: <a href="js/feed.js" type="text/javascript">feed.js</a></li>
<li>Javascript: <a href="js/feedDisplay.js" type="text/javascript">feedDisplay.js</a></li>
<li>Javascript: <a href="js/main.js" type="text/javascript">main.js</a></li>
</ul>
</section>

<section>
<h2 id="sc1_label">HTML Source Code</h2>
<div role="separator" id="sc1_start_sep" aria-labelledby="sc1_start_sep sc1_label" aria-label="Start of"></div>
<pre><code id="sc1"></code></pre>
<div role="separator" id="sc1_end_sep" aria-labelledby="sc1_end_sep sc1_label" aria-label="End of"></div>
<script>
sourceCode.add('sc1', 'ex1');
sourceCode.make();
</script>
<p>Please open <a href="feedDisplay.html">feedDisplay.html</a> and view source.</p>
</section>
</main>
<nav>
<!-- Update the pattern_ID parameter of this link to refer to the APG design pattern section related to this example. -->
<a href="../../#feed">Feed Design Pattern in WAI-ARIA Authoring Practices 1.1</a>
</nav>
</body>
Expand Down

0 comments on commit 346556b

Please sign in to comment.