Skip to content

Commit

Permalink
Merge branch 'master' into technique-generator
Browse files Browse the repository at this point in the history
  • Loading branch information
Michael Cooper committed Aug 28, 2018
2 parents a23dab1 + 8d7eaf8 commit ce79020
Show file tree
Hide file tree
Showing 723 changed files with 18,766 additions and 1,338 deletions.
30 changes: 27 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,12 +97,30 @@ The formal publication location for Understanding pages is currently https://www

## Editing Techniques

Techniques are in the techniques folder, and grouped by technology into sub-folders. Each technique is a standalone file, which is in HTML format with a regular structure of elements, classes, and ids. Techniques previously published for WCAG 2.0 are currently have the assigned ID of the technique as the filename, but new techniques should use a filename that is derived from a shortened version of the technique title.
Techniques are in the techniques folder, and grouped by technology into sub-folders. Each technique is a standalone file, which is in HTML format with a regular structure of elements, classes, and ids.

For example, a technique "Using the alt attribute on the img element to provide short text alternatives" might use "img-alt-short-text-alternatives.html" as the filename.
### Technique File Structure

The [technique template](techniques/technique-template.html) shows the structure of techniques. Main sections are in top-level &lt;section> elements with specific IDs: meta, applicability, description, examples, tests, related, resources. The description and tests sections are required; the applicability and examples sections are recommended; the related and resources sections are optional. The meta section provides context for the technique during authoring but is removed for publication. The title of the technique is in the `<h1>` element. Elements with `class="instructions"` provide information about populating the template. They should be removed as the technique is developed but if not removed, will be ignored by the generator. **Do not copy `class="instructions"` on real content.**

The generator used to publish techniques uses XML processing, so techniques must be well-formed XML. Techniques use HTML 5 structure so are actually [HTML Polyglot](https://www.w3.org/TR/html-polyglot/).

### Images, Examples, Cross References for Techniques

Techniques can include images. Place the image file in the `img` folder of the relevant technology - meaning all techniques for a technology share a common set of images. Use a relative link to load the image. Most images should be loaded with a `<figure>` element and labeled with a `<figcaption>` positioned at the bottom of the figure. Small inline images may be loaded with a `<img>` element with suitable `alt` text.

Techniques should include brief code examples to demonstrate how to author content that follows the technique. Code examples should be easy to read, and usually not complete content in themselves. More complete examples can be provided as [working examples](#user-content-provide-working-examples-of-techniques) (see below). Link to working examples at the bottom of each example, in a `<p class="working-example">` element, containing a relative link to `../../working-examples/{example-name}/`.

Cross references to other techniques may be provided where useful. Generally they should be provided in the "Related Techniques" section but can be provided elsewhere. Use a relative link to reference the technique, `{Technique ID}` if the same technology, or `../{Technology}/{Technique ID}` otherwise. If the technique is still under development and does not have a formal ID, reference the path to the development file. If the technique is under development in a different branch, use an absolute URI to the rawgit version of the technique.

Cross references to guidelines and success criteria should use a relative URI to the *Understanding* page for that item. Cross references to other parts of the guidelines should use an absolute URI to the guidelines as published on the W3C TR page, a URI beginning with `https://www.w3.org/TR/WCAG21/#`. Note that references to guidelines or success criteria to which techniques relate are added by the generator upon publication based on information in the Understanding documents, so redundant links to those is not normally needed or advised.

### Create Techniques

[General priorities and process to work on techniques are maintained in the wiki](https://www.w3.org/WAI/GL/wiki/Wcag21-techniques).

New techniques should use a filename that is derived from a shortened version of the technique title. Editors will assign the technique an ID and rename the file when it is accepted by the Working Group. For example, a technique "Using the alt attribute on the img element to provide short text alternatives" might use "img-alt-short-text-alternatives.html" as the filename. The editors will assign it a formal ID, and rename the file, when it is accepted by the Working Group.

Each new technique should be created in a new branch. Set-up of the branch and file is automated via the create-techniques.sh script, which can be run with bash. The command line is:

```Shell
Expand All @@ -127,7 +145,13 @@ Once a technique branch and file is set up, populate the content and request rev
* If you wish to reference the draft technique from an Understanding document, use the technique's rawgit URI.
* After a technique is approved, the chairs will assign it an ID and update links to it in the Undestanding documents.

### Provide Working Examples of Techniques
### Formatting Techniques

Techniques in the repository are plain HTML files with minimal formatting. For publication to the editors' draft and W3C location, techniques are formatted by an XSLT-based generator managed by Apache Ant running in Java. Most people do not need to worry about this, but relevant files are the [Ant build file](build.xml) and [XSLT files](xslt).

The generator compiles the techniques together as a suite with formatting and navigation. It enforces certain structures, such as ordering top-level sections described above and standardizing headings. It attempts to process cross reference links to make sure the URIs work upon publication. One of the most substantial roles is to populate the Applicability section with references to the guidelines or success criteria to which the technique relates. The information for this comes from the Understanding documents. Proper use of the technique template is important to enable this functionality, and mal-formed techniques may cause the generator to fail.

## Working Examples

Examples in techniques should be brief easy-to-consume code samples of how the technique is used in content. Therefore examples should focus on the specific features the technique describes, and not include related content such as style, script, surrounding web content, etc.

Expand Down
2 changes: 1 addition & 1 deletion techniques/aria/ARIA1.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ <h3>Using aria-describedby property to describe a Close button's action</h3>
&lt;div id="descriptionClose"&gt;Closing this window will discard any information entered and
return you back to the main page&lt;/div&gt;
</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/describedby-close.html">Example 1</a>
<p class="working-example">Working example: <a href="../../working-examples/aria-describedby-close/">Example 1</a>
</p>

</section>
Expand Down
2 changes: 1 addition & 1 deletion techniques/aria/ARIA10.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ <h3>Providing a short description for a complex graphic</h3>
&lt;/div&gt;

&lt;div id="star_id"&gt;4 of 5&lt;/div&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/ARIA10-example1.html">Providing a short description for a complex graphic</a>.
<p class="working-example">Working example: <a href="../../working-examples/aria-labelledby-description-complex-graphic/">Providing a short description for a complex graphic</a>.
</p>

</section>
Expand Down
2 changes: 1 addition & 1 deletion techniques/aria/ARIA14.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ <h3>A close button (X) in a pop-up box</h3>
This is a pop-up box.
&lt;button aria-label="Close" onclick="document.getElementById('box').style.display='none';" class="close-button"&gt;X&lt;/button&gt;
&lt;/div&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/box.html">Close button example</a>.
<p class="working-example">Working example: <a href="../../working-examples/aria-label-invisible-label-box/">Close button example</a>.
</p>

</section>
Expand Down
4 changes: 2 additions & 2 deletions techniques/aria/ARIA17.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ <h3>Social Security Number</h3>
&lt;input size="2" type="text" aria-required="true" title="Next 2 digits" /&gt;-
&lt;input size="4" type="text" aria-required="true" title="Last 4 digits" /&gt;
&lt;/div&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/ssn.html">Multiple part field groups</a>.</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-grouping-multipart-fields-ssn/">Multiple part field groups</a>.</p>

</section>
<section class="example">
Expand Down Expand Up @@ -52,7 +52,7 @@ <h3>Identifying radio groups</h3>
<pre xml:space="preserve">div[role=radiogroup] {
border: black thin solid;
} </pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/grouping-roles-example.html">using grouping roles to identify related form controls</a>.</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-grouping-related-fields/">using grouping roles to identify related form controls</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
2 changes: 1 addition & 1 deletion techniques/aria/ARIA18.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ <h3>Alert dialog</h3>
&lt;button&gt;Save and Continue&lt;/button&gt;
&lt;button&gt;Return to page and correct error&lt;/button&gt;
&lt;/div&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/aria-role-alertdialog.html">Alert dialog</a>.</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-alertdialog-identify-errors/">Alert dialog</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
2 changes: 1 addition & 1 deletion techniques/aria/ARIA19.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ <h3>Injecting error messages into a container with role=alert already present in
&lt;input type="submit" name="button" id="button" value="Submit"&gt;
&lt;/p&gt;
&lt;/form&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/aria-alert-validation.html">Using role=alert to identify errors</a>.</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-alert-identify-errors/">Using role=alert to identify errors</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
4 changes: 2 additions & 2 deletions techniques/aria/ARIA21.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ <h3>Using aria-invalid on required fields</h3>
&lt;/p&gt;
&lt;/form&gt;
&lt;/code&gt; </pre>
<p class="working-example"><a href="https://www.w3.org/WAI/WCAG21/working-examples/Form-AriaLiveWithJQ.html">Live example</a>.</p>
<p class="working-example"><a href="../../working-examples/aria-invalid-required-fields/">Working example: Using aria-invalid on required fields</a>.</p>

</section>
<section class="example">
Expand Down Expand Up @@ -100,7 +100,7 @@ <h3>Identifying errors in data format</h3>
background-repeat:no-repeat; background-position:right;
}
</pre>
<p class="working-example"><a href="https://www.w3.org/WAI/WCAG21/working-examples/form-alert3.html">Live example</a>.</p>
<p class="working-example"><a href="../../working-examples/aria-invalid-data-format/">Working example: Identifying errors in data format</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
6 changes: 3 additions & 3 deletions techniques/aria/ARIA9.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ <h3> A time-out input field with concatenated label</h3>
aria-labelledby="timeout-label timeout-duration timeout-unit"&gt;
&lt;span id="timeout-unit" tabindex="-1"&gt; minutes&lt;/span&gt;&lt;/p&gt;
&lt;/form&gt;</pre>
<p class="working-example">Working example, <a href="https://www.w3.org/WAI/WCAG21/working-examples/ex1.html">Time-out input field with concatenated label</a>, adapted from Easy ARIA tip #2: aria-labelledby and aria-describedby, an example put together by Marco Zehe.</p>
<p class="working-example">Working example, <a href="../../working-examples/aria-labelledby-time-out-input-concatenated-label/">Time-out input field with concatenated label</a>, adapted from Easy ARIA tip #2: aria-labelledby and aria-describedby, an example put together by Marco Zehe.</p>

</section>
<section class="example">
Expand All @@ -52,7 +52,7 @@ <h3>A simple data table with text inputs</h3>
&lt;td&gt;&lt;input type="text" size="20" aria-labelledby="sp div" /&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;</pre>
<p class="working-example">Working example, <a href="https://www.w3.org/WAI/WCAG21/working-examples/ex2.html">Using aria-labelledby for simple table with text inputs</a>, based on an example by Jim Thatcher.</p>
<p class="working-example">Working example, <a href="../../working-examples/aria-labelledby-table-text-inputs/">Using aria-labelledby for simple table with text inputs</a>, based on an example by Jim Thatcher.</p>

</section>
<section class="example">
Expand Down Expand Up @@ -141,7 +141,7 @@ <h3>A conference workshop booking table</h3>
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;</pre>
<p class="working-example">Working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/ex3.html">Conference workshop booking timetable</a>.</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-labelledby-workshop-booking-timetable/">Conference workshop booking timetable</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
2 changes: 1 addition & 1 deletion techniques/client-side-script/SCR14.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
Turn Alerts Off&lt;/button&gt;&lt;/p&gt;
</pre>

<p class="working-example">Working example of this code: <a href="https://www.w3.org/WAI/WCAG21/working-examples/enablealerts.html">Demonstration of Alerts</a>.</p>
<p class="working-example">Working example of this code: <a href="../../working-examples/script-enable-alerts/">Demonstration of Alerts</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
2 changes: 1 addition & 1 deletion techniques/client-side-script/SCR18.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ <h3>Checking multiple controls when the user submits the form</h3>
&lt;/p&gt;
&lt;/form&gt;
</pre>
<p class="working-example">This is demonstrated in the <a href="https://www.w3.org/WAI/WCAG21/working-examples/multiple-controls.html">working example of checking multiple controls when the user submits the form</a>.</p>
<p class="working-example">This is demonstrated in the <a href="../../working-examples/script-check-multiple-controls/">working example of checking multiple controls when the user submits the form</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
2 changes: 1 addition & 1 deletion techniques/client-side-script/SCR19.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
&lt;/body&gt;
&lt;/html&gt;</pre>

<p class="working-example"> Here is a working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/dynselect.html">Dynamic
<p class="working-example"> Here is a working example: <a href="../../working-examples/script-dynamic-select/">Dynamic
Select</a>
</p>

Expand Down
107 changes: 54 additions & 53 deletions techniques/client-side-script/SCR20.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,59 +11,60 @@
The following table suggests keyboard event handlers to pair mouse event handlers.
</p>

Device Handler Correspondences


Use...
...with



mousedown


keydown




mouseup


keyup




click

[1]


keypress

[2]




mouseover


focus




mouseout


blur




<p>
<table id="SCR20_mappings">
<caption>Device Handler Correspondences</caption>
<tbody>
<tr>
<th scope="col">Use...</th>
<th scope="col">...with</th>
</tr>
<tr>
<td>
<code>mousedown</code>
</td>
<td>
<code>keydown</code>
</td>
</tr>
<tr>
<td>
<code>mouseup</code>
</td>
<td>
<code>keyup</code>
</td>
</tr>
<tr>
<td>
<code>click
</code>
<sup>[1]</sup>
</td>
<td>
<code>keypress
</code>
<sup>[2]</sup>
</td>
</tr>
<tr>
<td>
<code>mouseover</code>
</td>
<td>
<code>focus</code>
</td>
</tr>
<tr>
<td>
<code>mouseout</code>
</td>
<td>
<code>blur</code>
</td>
</tr>
</tbody>
</table>
<p>
1 Although click is in principle a mouse event handler, most HTML and XHTML user agents also process this event when a native HTML control (e.g. a button or a link) is activated, regardless of whether it was activated with the mouse or the keyboard. In practice, therefore, it is not necessary to duplicate this event when adding handlers to natively focusable HTML elements. However, it is necessary when adding handlers to other events, such as in Example 2 below.</p>
<p>
2 Since the keypress event handler reacts to any key, the event handler function should check first to ensure the Enter key was pressed before proceeding to handle the event. Otherwise, the event handler will run each time the user presses any key, even the tab key to leave the control, and this is usually not desirable.
Expand Down
2 changes: 1 addition & 1 deletion techniques/client-side-script/SCR21.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@

<p>This example is limited to client-side scripting, and should be backed up with server-side validation. The example is limited to the creation of error messages when client-side scripting is available.
</p>
<p class="working-example">Here is a link to a working example: <a href="https://www.w3.org/WAI/WCAG21/working-examples/ex1.html">Form Validation</a>
<p class="working-example">Here is a link to a working example: <a href="../../working-examples/script-form-validation/">Form Validation</a>
</p>

</section>
Expand Down
2 changes: 1 addition & 1 deletion techniques/client-side-script/SCR22.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
...
</pre>

<p class="working-example">Working example of this code: <a href="https://www.w3.org/WAI/WCAG21/working-examples/ex1.html">Using script to control blinking</a>.</p>
<p class="working-example">Working example of this code: <a href="../../working-examples/script-control-blink/">Using script to control blinking</a>.</p>

</section>
</section><section id="tests"><h2>Tests</h2>
Expand Down
Loading

0 comments on commit ce79020

Please sign in to comment.