.LRN Zen Project: Standards
Created by Avni Khatri, last modified by Gustaf Neumann 22 Jun 2017, at 09:44 AM
Administration
- Goal: WAI-AA compliance
Steps to Cleanup (Zenify) a Package Page
- View Page in a browser and view source of page
- Check Doctype
- Check Title (optional)
- Check for H1-Hn and make sure they are in order. If not, make them so.
- Close all HTML tags
- Make sure there is no inline CSS
- Add an ALT attribute for IMG tags
- Add a TITLE attribute for A tags as necessary
- Check all user visible text and make sure it is using message keys instead of text
- If page has a form, make sure it is using formbuilder
- If page has data in tabular format, make sure it is using listbuilder
- Run accessibility tests
Doctype
- First target: Validated HTML 4.01 Strict
- Code:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> - Background: Choosing a DOCTYPE. Why not XHTML? See http://www.hixie.ch/advocacy/xhtml
Basic Page Requirements
- Title: should be in title tag, breadcrumbs, and h1 at top of page.
- To accomplish that, ADP pages using the <master> tag should pass the following properties.
<property name="title">Page Title</property>
<property name="context">{ { breadcrumb_url link_title } .. last_breadcrumb_element, title unless there is a good reason for it to be something else}</property>
You don't need to manually build the context bar UNLESS you want to include a URL that is not part of the site map. In other words, the context for 99% of pages should just be a one element list containing the page title or other text you want as the last element of the context bar. (DAVEB)
Title and context variables are set in the Tcl file so the property call looks like this
<property name="title">@title;literal@</property>
<property name="context">@context;literal@</property>
- To accomplish that, ADP pages using the <master> tag should pass the following properties.
- Use message keys instead of text. https://openacs.org/doc/i18n-convert.html
Applying new CSS and HTML clean-up
- Close HTML tags (LI, P, etc.)
- ID attributes must start with a letter
- Styles should be in CSS (no inline styles)
- Provide an ALT attribute for IMG tags (chekpoint 1.1 - priority 1 - A). The ALT text should be localized. When the image is used for layout only, set an empty string for ALT (ALT="").
- Clearly identify the target of each link (A tag) by providing an TITLE attribute (checkpoint 13.1 - priority 2 - AA). The text should be meaningful and localized. More Info: https://www.nngroup.com/articles/title-attribute/
- For data tables, identify row and column headers (checkpoint 5.1 - priority 1 - A). The best is to use list template when it's possible. Otherwise, make sure:
- your table has a summary tag
- you use <caption><thead> <tfooot><tbody> where appropriate.
- you give column and row headers a scope: <thead> <th id=""> <tbody> <td headers="">
- If you headers are really long you give them abbr.
<table class="list-table" cellpadding="3" cellspacing="1" summary="Data for folders"> <thead> <tr class="list-header"> <th class="list-table" id="folders_name">Name</th> <th class="list-table" id="folders_type">Type</th> <th class="list-table" id="folders_size">Size</th> </tr> </thead> <tbody> <tr class="odd"> <td class="list-table" headers="folders_name"><a href="#">Course 2 Files</a></td> <td class="list-table" headers="folders_type">folder</td> <td class="list-table" headers="folders_size">2 items</td> </tr> <tr class="even"> <td class="list-table" headers="folders_name"><a href="#">Course 1 Files</a></td> <td class="list-table" headers="folders_type">folder</td> <td class="list-table" headers="folders_size">2 items</td> </tr> </tbody> </table>
Form Builder and Template
- All forms will use the default form template (standard.adp) now.
- Therefore, there is no longer a need to have the "style" attribute in the formtemplate tag. (i.e. <formtemplate id=zen style=inline>). We can get rid of this attribute on all forms that currently use it.
- Instead, there are different CSS classes that can be applied to all forms to get the same effect of inline.adp, plainest.adp, and other form templates while actually using the zen-ified standard.adp. The form class to be used is passed in the "html" parameter of the ad_form proc.
- Example:
- ad_form -name "zen" -method post -html {class vertical-form}..... -form {....}
- This will render: <form name="zen" method="post" class="vertical-form">
- Example:
- List of form classes available and example URLs.
- Note: Example forms are checked into the 5.3 branch. Example files are listed below.
- margin-form : This is the default form class if none is passed to the ad_form proc
- /packages/theme-zen/doc/forms/index*
- vertical-form
- /packages/theme-zen/doc/forms/form-vertical*
- inline-form : Replaces inline.adp
- /packages/theme-zen/doc/forms/form-inline*
- Example:
- Change:
- <formtemplate id=zen style=inline>
- To:
- <formtemplate id=zen>
- And modify the tcl ad_form call to pass a class to the form, so it will be like this:
- ad_form -name "zen" ... -html {... class inline-form}.... -form {...}
- Change:
- If the form you working on started out as <formtemplate id="zen">, then you probably don't need to change the formtemplate or the form class. The defaults will most likely work fine. Look at the page in a browser and see how it is rendered. If you have any questions about which formtemplate to use, ask Mark Wylie.
- Fieldsets and Fieldset Legends
- Legends need to be short, there is no line wrapping for legends
- more fieldset and legend info coming soon
- If you have to hand code a form, it should look something like this:
<form class="margin-form">
<fieldset>
<legend>Short Legend</legend>
<div class="form-item-wrapper">
<div class="form-label">
<label for="first_name">First Name</label>
<div class="form-required-mark">(required)</div>
</div>
<div class="form-widget">
<input type="text" name="first_name" id="first_name" size="30" />
</div>
<div class="form-help-text">
<img src="images/icons/info.png" alt="info" width="16" height="16" /> Some info text
</div>
<div class="form-error">
<img src="images/icons/exclamation.png" alt="error" width="16" height="16" /> This field was in error
</div>
</div>
<div class="form-button">
<input type="submit" name="formbutton:submit" value="submit" />
</div>
</fieldset>
</form>
Using sections in ad_form
The "section" element property is not longer supported. See Web_Forms for an example of how to use sections in ad-form.
List Builder and Template
When creating a list template that contains links, provide a title attribute (with a meaningful and localized text) for each of them (checkpoint 13.1 - priority 2 - AA). Example:
template::list::create \
-name messages \
-html [list summary "Summary title"] \
-caption "Optional caption" \
-multirow messages \
-page_size $page_size \
-page_query_name messages_select_paginate \
-pass_properties { moderate_p } \
-actions $actions \
-elements {
subject {
label "[_ forums.Subject]"
link_url_col message_url
link_html {title "[_ forums.goto_thread_subject]" class "myclass"}
}
}
This is also true for actions list. Example:
lappend actions [_ forums.Post_a_New_Message]\
[export_vars -base "${base_url}message-post" { forum_id }]\
[_ forums.Post_a_New_Message]
New Parameters
- caption - optional
- summary - required for AA. There is a default in place: "Data for %list_name%"
W3C Web Content Accessibility Checkpoints
Zen aims at being Level AA compliant (priority 2 checkpoints):
- Checkpoints: Web Content Accessibility Guidelines 1.0
- Checklist for checkpoints of WCAG 1.0
- Techniques for WCAG 1.0
Tools for Checking Accessibility
Accessibility Evaluation Toolbar (Firefox):
- Disable javascript: alternatives should be provided to js actions
- Disable styles (CSS): to verify the render for text only browsers
- Disable images: ALT texts should appear for each image
- Display title attribute: a meaningful title should be provided for each link
- Linearize page: tables should linearize well
- Validate local HTML
- Validate local CSS
- Validate local accessibility
- Validate package and inline (if you're using the new inline class) CSS.
Colour Contrast Analyser ( Firefox):
- Use the "Luminosity Contrast Ratio" option.
- For the default CSS, the page should pass at level 2
- For the HC (High Contrast) CSS, the page should pass at level 3
Fangs, the Screen Reader Emulator (Firefox)
Hera (automatic and manual reports)
WebXact (if HERA is not working)
Others tips
- Use Opera's View/Small Screen mode to test the handheld.css.
Important Checkpoints
- WCAG - Checkpoint 3.5: Use header elements to convey document structure
and use them according to specification. - WCAG - Checkpoint 5.3: Do not use tables for layout unless the table makes sense when linearized. Otherwise, if the table does not make sense, provide an alternative equivalent. Documents with two columns or more use tables to give structure. Layers should be used, instead.
