diff --git a/README.md b/README.md index d4735dc30a..24c8c4e411 100644 --- a/README.md +++ b/README.md @@ -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 <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 `
` 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 @@ -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. diff --git a/techniques/aria/ARIA1.html b/techniques/aria/ARIA1.html index 8e3676097b..e368cc6069 100644 --- a/techniques/aria/ARIA1.html +++ b/techniques/aria/ARIA1.html @@ -19,7 +19,7 @@
Working example: Example 1 +
Working example: Example 1
diff --git a/techniques/aria/ARIA10.html b/techniques/aria/ARIA10.html index 06db203c01..a0e4267dc3 100644 --- a/techniques/aria/ARIA10.html +++ b/techniques/aria/ARIA10.html @@ -16,7 +16,7 @@Working example: Providing a short description for a complex graphic. +
Working example: Providing a short description for a complex graphic.
diff --git a/techniques/aria/ARIA14.html b/techniques/aria/ARIA14.html index db98bd21b6..d948ed9460 100644 --- a/techniques/aria/ARIA14.html +++ b/techniques/aria/ARIA14.html @@ -17,7 +17,7 @@Working example: Close button example. +
Working example: Close button example.
diff --git a/techniques/aria/ARIA17.html b/techniques/aria/ARIA17.html index f378591898..ffaa7ab550 100644 --- a/techniques/aria/ARIA17.html +++ b/techniques/aria/ARIA17.html @@ -17,7 +17,7 @@Working example: Multiple part field groups.
+Working example: Multiple part field groups.
div[role=radiogroup] { border: black thin solid; }-
Working example: using grouping roles to identify related form controls.
+Working example: using grouping roles to identify related form controls.
Working example: Alert dialog.
+Working example: Alert dialog.
Working example: Using role=alert to identify errors.
+Working example: Using role=alert to identify errors.
Working example, Time-out input field with concatenated label, adapted from Easy ARIA tip #2: aria-labelledby and aria-describedby, an example put together by Marco Zehe.
+Working example, Time-out input field with concatenated label, adapted from Easy ARIA tip #2: aria-labelledby and aria-describedby, an example put together by Marco Zehe.
Working example, Using aria-labelledby for simple table with text inputs, based on an example by Jim Thatcher.
+Working example, Using aria-labelledby for simple table with text inputs, based on an example by Jim Thatcher.
Working example: Conference workshop booking timetable.
+Working example: Conference workshop booking timetable.
Working example of this code: Demonstration of Alerts.
+Working example of this code: Demonstration of Alerts.
This is demonstrated in the working example of checking multiple controls when the user submits the form.
+This is demonstrated in the working example of checking multiple controls when the user submits the form.
Here is a working example: Dynamic
+ Here is a working example: Dynamic
Select
+
Use... | +...with | +
---|---|
+ mousedown
+ |
+
+ keydown
+ |
+
+ mouseup
+ |
+
+ keyup
+ |
+
+ click
+
+ [1]
+ |
+
+ keypress
+
+ [2]
+ |
+
+ mouseover
+ |
+
+ focus
+ |
+
+ mouseout
+ |
+
+ blur
+ |
+
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.
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. diff --git a/techniques/client-side-script/SCR21.html b/techniques/client-side-script/SCR21.html index 8aa3315ce7..4ae80d3877 100644 --- a/techniques/client-side-script/SCR21.html +++ b/techniques/client-side-script/SCR21.html @@ -164,7 +164,7 @@
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.
-Here is a link to a working example: Form Validation +
Here is a link to a working example: Form Validation
Working example of this code: Using script to control blinking.
+Working example of this code: Using script to control blinking.
Working example of this code: Toggle navigation bar with a link.
+Working example of this code: Toggle navigation bar with a link.
Working example of this code: Toggle table of contents with a button.
+Working example of this code: Toggle table of contents with a button.
Working example of this code: Creating Divs with Actions using JavaScript.
+Working example of this code: Creating Divs with Actions using JavaScript.
Working example of this code: Providing link expansions on demand.
+Working example of this code: Providing link expansions on demand.
This example validates required fields as well as fields where a specific format is required. When an error is identified, the script inserts a list of error messages into the DOM and moves focus to them.
+ +HTML and Javascript code @@ -371,7 +376,7 @@ } -
Working example of this technique implemented using PHP, Javascript, CSS and XHTML: Form Validation Example.
+Working example of this technique implemented using PHP, Javascript, CSS and XHTML: Form Validation Example.
A working example of this code, Example of using script to scroll content and providing a mechanism to pause it, is available.
+A working example of this code, Example of using script to scroll content and providing a mechanism to pause it, is available.
A working example of this code is available. Refer to Creating Action Links using JavaScript.
+A working example of this code is available. Refer to Creating Action Links using JavaScript.
A working example of this code is available. Refer to Creating Action Buttons using JavaScript.
+A working example of this code is available. Refer to Creating Action Buttons using JavaScript.
Working example of this code: Expanding Scrolling Text in Place.
+Working example of this code: Expanding Scrolling Text in Place.
Working example of this code: Example of highlighting elements that receive focus.
+Working example of this code: Example of highlighting elements that receive focus.
h1 { font-size: 2em; } p, label, input { font-size: 1em; }-
Working example of this code: Example of resizing input with CSS.
+Working example of this code: Example of resizing input with CSS.
Working example of this code: Example of resizing radio buttons and checkboxes with CSS.
+Working example of this code: Example of resizing radio buttons and checkboxes with CSS.
A working example of this code, Using a JavaScript control to apply a different external CSS file, is available.
+A working example of this code, Using a JavaScript control to apply a different external CSS file, is available.
A working example of this code, Using a client-side JavaScript to change a CSS property, is available.
+A working example of this code, Using a client-side JavaScript to change a CSS property, is available.
A working example of this code, Using PHP $_GET to apply a different external CSS file, is available.
+A working example of this code, Using PHP $_GET to apply a different external CSS file, is available.
The example below uses two files
The server-side code outputs a normal link element for the stylesheet that the user chooses and link elements with "alternate stylesheet" for the other styles. The code can thus be used as a fallback for the client-side code in the second example.
@@ -495,8 +495,8 @@A user's selection can be made persistent across pages, and from one visit to another, by storing information on the user's computer via a cookie. This functionality requires cookies to be supported by and allowed on the user's computer. Cookies can be created, read, modified and erased by using client-side scripts, such as Javascript, or by server-side scripts, such as CGI scripts. Reliance on client-side technologies will require the support and availability of the technology on the user's computer in addition to supporting and allowing cookies.
Information on creating and using cookies can be found on the web. Here are some suggestions:
It is recommended that authors test for cookie support and provide an extra control if cookies are not supported. This extra control should include information about the persistence of the selection, such as "Apply selection to all pages". The message or page presented to the user in response to selecting the extra control provides information about the cookie requirement and their options for solving it. In the event that the user is unable to turn cookie support on, include a statement about what this will mean for them if they choose to continue to browse the site and provide information about how they can adjust their user agent to achieve similar results.
For example, "Your browser is not configured to accept cookies. On this site, cookies are required in order to apply your selected changes across all of the pages of the site. To find out how to enable cookies on your computer, visit How to Enable Cookies. Note that this may require administrative rights for the computer you are using. Without cookie support, your settings will not persist to include other pages on this site. We are endeavoring to provide this functionality without relying on your computer's capability. In the meantime, you will be able to select the change for each page that you visit."
- - -Current best practice for implementing JavaScript in an HTML or XHTML page is to use it in a way that separates the behavior of content from its structure and presentation. The terms 'Progressive Enhancement' and 'Unobtrusive JavaScript' are often used to describe scripts that enhance or improve the functionality of a page, yet transform gracefully so that content continues to function even when JavaScript is not supported.
Here are some suggested starting points for more information: