View · Index

.LRN Zen Project: Standards

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.
1. 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>
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.
1. 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.
2. 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">
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 {...}
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
1. Legends need to be short, there is no line wrapping for legends
2. 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):

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.

Popular tags

17 (1), 5.10 (1), 5.10.0 (2), 5.10.1 (1), 5.9.0 (3), 5.9.1 (4), ad_form (1), ADP (1), ajax (1), aolserver (1), asynchronous (2), bgdelivery (3), bootstrap (1), bugtracker (1), CentOS (1), COMET (1), compatibility (1), CSP (1), CSRF (1), cvs (3), debian (7), docker (2), docker-compose (1), emacs (2), engineering-standards (1), exec (1), fedora (1), FreeBSD (1), guidelines (1), host-node-map (1)

No registered users in community xowiki
in last 30 minutes

Contributors

OpenACS.org

References to this Page: en:docs-dev-tutorial, en:coding-standards-index, en:dotlrn-zen-bugbash Categories: Zen Project (OpenACS.org), Coding Standards (OpenACS.org), Accessibility (OpenACS.org)