Filtered by category Coding Standards, 11 - 19 of 19 Postings (all, summary)

How to contribute code that passes accessibility tests

Created by Rocael Hernández Rizzardini, last modified by Benjamin Brink 30 Jun 2017, at 06:10 AM

About this document

Status: DRAFT
Updated: 11-jun-2009

Accessibility Policy

The policy for .LRN is published at .LRN website: Accessibility Policy

Corresponding policy for OpenACS is currently being written and will be published soon.

The conformance level to be satisfied is explained in the "Accessibility Conformance Level" section of the .LRN Accessibility Policy.

The "Accessibility page" refered by the .LRN Accessibility Policy states the conformance level and its domain of aplication for each version of the software.

Web Content Accessibility Guidelines

Note: Although automatic tools, such as TAW and "Cynthia says", may be useful to help the developer/author in addressing accessibility issues by providing informative reports, they can not certify the accessibility level of a page since many things need a manual review. Also, those tools won't be able to check a page protected by user and password (they would report on the login page, the one they can actually reach).

WCAG version 2.0

Understanding WCAG 2.0: a "must read"
The guidelines
How to meet WCAG 2.0 (quick reference)
Techniques and Failures for the Success Criteria of WCAG 2.0

WCAG version 1.0

The guidelines: explain how to make Web content accessible to people with disabilities.
Checklist of checkpoints to satify for each level of conformance. Each checkpoint is followed by one or more links to techniques in the following documents:
- "Core Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-CORE-TECHNIQUES]), which discusses the accessibility themes and general techniques that apply across technologies.
- "HTML Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-HTML-TECHNIQUES]), which provides examples and strategies for authoring accessible Hypertext Markup Language (HTML) content.
- "CSS Techniques for Web Content Accessibility Guidelines 1.0" ([WCAG10-CSS-TECHNIQUES]), which provides examples and strategies to help authors write Cascading Style Sheets (CSS) as part of accessible content design.
Techniques: gateway to the aforementioned specific ones.

Contributing Code

Once the requirements are met, to contribute your code follow these instructions (one of the two):

How to contribute to OpenACS
Contributing code for .LRN: submit your proposal to the .LRN leadership team by:
- posting at the .LRN Q&A forum
- joining the weekly meeting on IRC (tuesday at 18:00 CET/CEST)

Resources

on-site resources

(addressing) Accessibility in .LRN and OpenACS: tutorial from the OpenACS/.LRN conference in Valencia (nov 2008), based on WCAG version 1.0.
Accessibility Guidelines for OpenACS/.LRN developers: slides from an online tutorial on may 2009, based on WCAG version 2.0.
.LRN Zen project Standards

External resources

Web Accessibility Initiative
Web Accessibility in Mind
456 Berea St: Articles and news on web standards, accessibility, and usability

If you need more information on how to address accessibility, post your questions at the forums

References to this Page: en:coding-standards-index Categories: .LRN (OpenACS.org), Coding Standards (OpenACS.org), Accessibility (OpenACS.org)

.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.
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.

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)

Emacs as an OpenACS IDE

Created by OpenACS community, last modified by Gustaf Neumann 13 Jun 2017, at 10:30 AM

emacs integrated development environment for OpenACS

emacs documentation: http://www.gnu.org/software/emacs/manual/html_node/

Emacs uses major and minor modes that provide a UI context for editing various file types. Here are some useful ones for working with OpenACS:

CVS Mode Emacs with OpenACS

I use M-x cvs-examine to update and check in code when I am working with OpenACS. One thing that is a pain with CVS is that cvs diff does not tell you what you are going to get if you update, it only tells you what is changed in your local copy.

You can use M-x cvs-examine and then type "d e" next to any of the files in your checkout in the *cvs* buffer to open ediff mode and then interactively merge what's in CVS with your local changes. In ediff mode you use n/p to got to the next/previous difference. You can copy changes from the CVS buffer to your local copy using a/b to copy the the buffer marked A to B or B to A. Type ? on the ediff window to get a list of other commands.

OpenACS Mode for Emacs

See historical page describing oacs.el http://web.archive.org/web/20040621200046/www.thecodemill.biz/services/oacs/

Download: oacs.el.tar updated 2006-08-15 . The lastest version includes nXML mode support in addition to PSGML support. There are good installation instructions in the INSTALL.txt file. A quick install guide for Debian

sudo su -
cd /usr/share/emacs/site-lisp
wget http://www.emacswiki.org/elisp/color-occur.el
wget https://openacs.org/storage/view/xowiki-resources%5C/oacs.el.tar
tar xf oacs.el.tar
apt-get install psgml mmm-mode

# Alternatively compile manually
wget http://www.lysator.liu.se/~lenst/about_psgml/psgml-1.2.5.tar.gz
tar xfz psgml-1.2.5.tar.gz
cd psgml-1.2.5
./configure
make install
cd ..
wget http://switch.dl.sourceforge.net/sourceforge/mmm-mode/mmm-mode-0.4.8.tar.gz
tar xfz mmm-mode-0.4.8.tar.gz
cd mmm-mode-0.4.8
./configure
make install

After this login as the user who is doing the development and edit you .emacs file.

 (add-to-list 'load-path "/usr/share/emacs/site-lisp/oacs")
 (require 'oacs)
 (setq user-full-name "<yourname>")
 (setq user-mail-address "<your email>")
 (add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))
 (add-to-list 'auto-mode-alist '("\\.adp" . html-mode))

For recent Emacs versions (> 2008), modify oacs-nxml.el in the downloaded tarball:

 line 30: (load "nxml-mode.el")  instead of (load "rng-auto.el")

See http://lists.gnu.org/archive/html/emacs-devel/2008-01/msg00947.html

Also, you may need to modify adp.rnc to the correct path to the xhtml.rnc schema on your installation. On OS X, for example, line 5 should read:

include "/Applications/Emacs.app/Contents/Resources/etc/schema/xhtml.rnc"

The following was written by Bart the author of oacs.el

OpenACS lacked a good Integrated Development Environment and as I use Emacs for almost everything it was only natural to fill the void. The Emacs OACS module is an extension to GNU Emacs, the extensible, customizable, self-documenting real-time display editor.

Development status

Emacs OACS's development is driven by the needs I encounter in my OpenACS projects. Development takes place in my spare time. At this stage the code is the documentation. I lack the time to write a proper article. However, as Emacs OACS addresses the issues described in articles XQL Document Type Definition and Replacing SQL bind vars in Emacs some background information can be found in those articles.

Forum thread: Beta Emacs OACS module available

Useful commands

Formating TCL

M-o ft to re-format Tcl code. See code for details.
M-o fh to reformat Html or Adp code.
M-o fs to reformat Sql code.
M-x oacs-format-separate-tags to separate adjacent tags. E.g. <tr><td>
M-x oacs-format-includes to place all include attribubtes on a separate line.
```
 
```

Code navigation

M-o oo to search for any custom regular expression.
M-o on to search the log for Notice oacs-dbg messages. That is a Notice level message created with the macro 'oddbg'.
M-o od to search the log for Debug oacs-dbg messages.
M-o oe to search the log for Error oacs-dbg messages. Etc for all other ns_log levels.
M-o op to browse Tcl libraries for procedure definitions. This is by far my favorite way of navigating a library!
M-o fp (find-file-at-point) to NSD error log mode.
M-o rl to revert the logfile
M-o ml to to open an error log file and monitor the changes to the log.

Editing docbook xml

editing via Muse mode

https://www.emacswiki.org/emacs?action=browse;oldid=MuseMode;id=EmacsMuse

editing via nXML mode

See https://openacs.org/doc/nxml-mode.html

psgml mode

See:

Developing with emacs

To make emacs display .vuh files similar to .tcl files, add to .emacs file:

 (add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))

To make emacs display .adp files similar to .html files, add to .emacs file:

 (add-to-list 'auto-mode-alist '("\\.adp" . html-mode))

Common command shortcuts

Minor Modes

 M-x global-font-lock-mode highlights syntax using colors
 M-x transient-mark-mode   shows a highlighted text region
 M-x show-paren-mode       shows matching parentheses (and when the do not)

Move, Search and Replace

 M-x goto-line             go to a specific line in a file
 M-x goto-char             go to a specific character number in a file
 M-C-f                     search forward for matching brace
 M-C-b                     search backward for matching brace
 M-x replace-regexp        search/replace using regular expressions
 M-x query-replace-regexp  query/search/replace using regular expressions
   note \\( and \\) for start and end subgroups
 M-x grep                  grep creates new buffer with results
                           for fast loading/editing search hits

Useful "sleepers" (not found in many shortcut sheets)

 fg<cr>                    restart a suspended emacs session from commandline
 C-q <key press>           add a key without emacs interpreting the key binding

You can configure emacs to create 4 spaces when you press the tab key--important for meeting coding standards. Add this to your .emacs file:

(setq-default tab-width 4 indent-tabs-mode nil)

other useful quicksheets

References to this Page: en:docs-dev-tutorial, en:docs-eng, en:coding-standards-index, en:INTRODUCTION, en:code-formatting, en:Documentation_Project_Plan, en:docs-eng-toc Categories: Subsystems Documentation (OpenACS.org), Tutorials for Programmers (OpenACS.org), Coding Standards (OpenACS.org)

WCAG 1.0 Checkpoints

Created by Emmanuelle Raffenne, last modified by Gustaf Neumann 02 Jun 2017, at 09:06 AM

Status at 21 october 2008 (OpenACS 5.4.3 and .LRN 2.4.1)

A summary for US Section 508 is available at LINK_TO_WIKIPAGE

See Checklist of Checkpoints for Web Content Accessibility Guidelines 1.0 for details

How to read this document

Accessibility Compliance Level

Level A means that all the priority 1 checkpoints are in state "Y" or "n/a".
Level AA means that level A has been reached + all the priority 2 checkpoints are in state "Y" or "n/a"
Level AAA means that level AA has been reached + all the priority 3 checkpoints are in state "Y" or "n/a"

Checkpoint Status

Y: 100% of the pages comply with the checkpoint or the exceptions are clearly identified and listed in the accessibility statement.
N: NOT 100% of the pages comply with the checkpoint, exceptions are NOT identified.
n/a: the situation described in the checkpoint is not applicable in ANY of the pages

OpenACS-specific Techniques for Checkpoints

Each checkpoint is identified with a number which links to the OpenACS-specific techniques to apply it.

Note: the links are dead right now, but will point to OpenACS-specific techniques to implement them.

Priority 1 checkpoints

In General (Priority 1)	Yes	No	N/A
1.1 Provide a text equivalent for every non-text element (e.g., via "alt", "longdesc", or in element content). This includes: images, graphical representations of text (including symbols), image map regions, animations (e.g., animated GIFs), applets and programmatic objects, ascii art, frames, scripts, images used as list bullets, spacers, graphical buttons, sounds (played with or without user interaction), stand-alone audio files, audio tracks of video, and video.	Y
2.1 Ensure that all information conveyed with color is also available without color, for example from context or markup.	Y
4.1 Clearly identify changes in the natural language of a document's text and any text equivalents (e.g., captions).	Y
6.1 Organize documents so they may be read without style sheets. For example, when an HTML document is rendered without associated style sheets, it must still be possible to read the document.	Y
6.2 Ensure that equivalents for dynamic content are updated when the dynamic content changes.			n/a
7.1 Until user agents allow users to control flickering, avoid causing the screen to flicker.	Y
14.1 Use the clearest and simplest language appropriate for a site's content.		N e.g.: portlet
And if you use images and image maps (Priority 1)	Yes	No	N/A
1.2 Provide redundant text links for each active region of a server-side image map.			n/a
9.1 Provide client-side image maps instead of server-side image maps except where the regions cannot be defined with an available geometric shape.			n/a
And if you use tables (Priority 1)	Yes	No	N/A
5.1 For data tables, identify row and column headers.	Y
5.2 For data tables that have two or more logical levels of row or column headers, use markup to associate data cells and header cells.	Y
And if you use frames (Priority 1)	Yes	No	N/A
12.1 Title each frame to facilitate frame identification and navigation.	Y
And if you use applets and scripts (Priority 1)	Yes	No	N/A
6.3 Ensure that pages are usable when scripts, applets, or other programmatic objects are turned off or not supported. If this is not possible, provide equivalent information on an alternative accessible page.		N lorsm
And if you use multimedia (Priority 1)	Yes	No	N/A
1.3 Until user agents can automatically read aloud the text equivalent of a visual track, provide an auditory description of the important information of the visual track of a multimedia presentation.			n/a
1.4 For any time-based multimedia presentation (e.g., a movie or animation), synchronize equivalent alternatives (e.g., captions or auditory descriptions of the visual track) with the presentation.			n/a
And if all else fails (Priority 1)	Yes	No	N/A
11.4 If, after best efforts, you cannot create an accessible page, provide a link to an alternative page that uses W3C technologies, is accessible, has equivalent information (or functionality), and is updated as often as the inaccessible (original) page.		N lorsm

Priority 2 checkpoints

In General (Priority 2)	Yes	No	N/A
2.2 Ensure that foreground and background color combinations provide sufficient contrast when viewed by someone having color deficits or when viewed on a black and white screen. [Priority 2 for images, Priority 3 for text].	Y
3.1 When an appropriate markup language exists, use markup rather than images to convey information.	Y
3.2 Create documents that validate to published formal grammars.	Y
3.3 Use style sheets to control layout and presentation.	Y
3.4 Use relative rather than absolute units in markup language attribute values and style sheet property values.		N calendar
3.5 Use header elements to convey document structure and use them according to specification.	Y
3.6 Mark up lists and list items properly.	Y
3.7 Mark up quotations. Do not use quotation markup for formatting effects such as indentation.	Y
6.5 Ensure that dynamic content is accessible or provide an alternative presentation or page.			n/a
7.2 Until user agents allow users to control blinking, avoid causing content to blink (i.e., change presentation at a regular rate, such as turning on and off).	Y
7.4 Until user agents provide the ability to stop the refresh, do not create periodically auto-refreshing pages.	Y
7.5 Until user agents provide the ability to stop auto-redirect, do not use markup to redirect pages automatically. Instead, configure the server to perform redirects.	Y
10.1 Until user agents allow users to turn off spawned windows, do not cause pop-ups or other windows to appear and do not change the current window without informing the user.	Y
11.1 Use W3C technologies when they are available and appropriate for a task and use the latest versions when supported.	Y
11.2 Avoid deprecated features of W3C technologies.	Y
12.3 Divide large blocks of information into more manageable groups where natural and appropriate.			n/a
13.1 Clearly identify the target of each link.	Y
13.2 Provide metadata to add semantic information to pages and sites.	Y
13.3 Provide information about the general layout of a site (e.g., a site map or table of contents).	Y
13.4 Use navigation mechanisms in a consistent manner.	Y
And if you use tables (Priority 2)	Yes	No	N/A
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 (which may be a linearized version).	Y
5.4 If a table is used for layout, do not use any structural markup for the purpose of visual formatting.	Y
And if you use frames (Priority 2)	Yes	No	N/A
12.2 Describe the purpose of frames and how frames relate to each other if it is not obvious by frame titles alone.	Y
And if you use forms (Priority 2)	Yes	No	N/A
10.2 Until user agents support explicit associations between labels and form controls, for all form controls with implicitly associated labels, ensure that the label is properly positioned.	Y
12.4 Associate labels explicitly with their controls.	Y
And if you use applets and scripts (Priority 2)	Yes	No	N/A
6.4 For scripts and applets, ensure that event handlers are input device-independent.	Y
7.3 Until user agents allow users to freeze moving content, avoid movement in pages.			n/a
8.1 Make programmatic elements such as scripts and applets directly accessible or compatible with assistive technologies [Priority 1 if functionality is important and not presented elsewhere, otherwise Priority 2.]	Y
9.2 Ensure that any element that has its own interface can be operated in a device-independent manner.			n/a
9.3 For scripts, specify logical event handlers rather than device-dependent event handlers.	Y

Priority 3 checkpoints

In General (Priority 3)	Yes	No	N/A
4.2 Specify the expansion of each abbreviation or acronym in a document where it first occurs.		N
4.3 Identify the primary natural language of a document.	Y
9.4 Create a logical tab order through links, form controls, and objects.		N
9.5 Provide keyboard shortcuts to important links (including those in client-side image maps), form controls, and groups of form controls.		N
10.5 Until user agents (including assistive technologies) render adjacent links distinctly, include non-link, printable characters (surrounded by spaces) between adjacent links.	Y
11.3 Provide information so that users may receive documents according to their preferences (e.g., language, content type, etc.)	Y
13.5 Provide navigation bars to highlight and give access to the navigation mechanism.	Y
13.6 Group related links, identify the group (for user agents), and, until user agents do so, provide a way to bypass the group.		N
13.7 If search functions are provided, enable different types of searches for different skill levels and preferences.		N
13.8 Place distinguishing information at the beginning of headings, paragraphs, lists, etc.			n/a
13.9 Provide information about document collections (i.e., documents comprising multiple pages.).	Y
13.10 Provide a means to skip over multi-line ASCII art.			n/a
14.2 Supplement text with graphic or auditory presentations where they will facilitate comprehension of the page.			n/a
14.3 Create a style of presentation that is consistent across pages.		N
And if you use images and image maps (Priority 3)	Yes	No	N/A
1.5 Until user agents render text equivalents for client-side image map links, provide redundant text links for each active region of a client-side image map.			n/a
And if you use tables (Priority 3)	Yes	No	N/A
5.5 Provide summaries for tables.		N
5.6 Provide abbreviations for header labels.		N
10.3 Until user agents (including assistive technologies) render side-by-side text correctly, provide a linear text alternative (on the current page or some other) for all tables that lay out text in parallel, word-wrapped columns.		N
And if you use forms (Priority 3)	Yes	No	N/A
10.4 Until user agents handle empty controls correctly, include default, place-holding characters in edit boxes and text areas.		N

References to this Page: en:coding-standards-index Categories: Zen Project (OpenACS.org), Coding Standards (OpenACS.org), Accessibility (OpenACS.org)

Web Lists / Tables

Created by Malte Sussdorff, last modified by Gustaf Neumann 24 Apr 2017, at 08:44 AM

If you have a table to be displayed on your webpage, use listbuilder (template::list::create) to create it. There is some documentation here and https://openacs.org/wiki/list%20builder which will be moved here real soon now ;).

One standard, which you should try to follow for re-usability, is to put the created list in a separate include file, so you could call it from various pages and packages. Things to keep in mind when doing this:

Pass a list of rows so you know which columns should be displayed on your page
Name the "orderby" field specific to the type of list: "tasks_orderby" "projects_orderby"
You might want to do the same with filters (to be on the safe side)

References to this Page: en:coding-standards-index, en:docs-eng-toc Categories: Coding Standards (OpenACS.org)

Logging Conventions

Created by Gustaf Neumann, last modified by Gustaf Neumann 08 Apr 2016, at 09:16 AM

The following conventions for severity levels (specified as first argument in ns_log) should be used.

Notice: Something interesting occurred. A "notice" shows typically a state change, start/end of some jobs, etc. This level can be as well used of temporary debugging, but such messages should be removed after some time.
Warning: Something that could mean something bad occurred. A "warning" indicates an unexpected situation, which requires attention of an developer and a corrective measure in the not-to-distant future. Usage of deprecated code or code using not following the engineering guidelines are of such type.
Error: Something bad occurred. An "error" is a malfunction, that must be investigated by a developer. An error is an unhandled exception. The error.log file should be free of errors.
Bug: Something occurred that implies that there is a bug in the code.
Debug: This logging level is typically just activated during debugging.
Dev: This logging level is typically just activated during development to inspect the behavior of new code. Such logging statements are typically removed once development has reached a stable point.

References to this Page: en:coding-standards-index Categories: Coding Standards (OpenACS.org)

Tcl pages

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 24 Dec 2015, at 10:48 AM

Always use Page Contracts:

All Tcl-implemented pages should use page contracts such as e.g.:

ad_page_contract {
    ... purpose ...
    @author ...
    @creation-date ...
} {
    object_id:naturalnum,notnull
    {verbose:boolean false}
    {color:word ""}
}

Constrain arguments passed via query or form variables as strong as possible

All user provide content is potentially a security thread, since these values might lead to SQL-injection or XSS attacks. Therefore constrain the passed arguments as far as possible (see above), and validate the values further if necesary.
Avoid putting in HTML in Tcl scripts

Try to make use of OpenACS Templating or http://your.openacs/doc/acs-templating/. If you can't avoid it try to isolate the HTML into a proc so editing the layout will be easier.
Avoid Quoting Hell

If programmatic HTML-code generation is required, make sure that everything is quoted sufficiently and use the Tcl command subst to improve readability:
```
set href [export_vars -base admin/index -vars {foo bar]
set html [subst {
   <a href="[ns_quotehtml $href]">Hello world</a>
}]
```
Read the Tcl Style guide

This is the Tcl styleguide (PDF), try to apply relevant guidelines. In particular chapter 4,5 and 7.

References to this Page: en:coding-standards-index, en:docs-eng-toc, en:security-guidelines Categories: Coding Standards (OpenACS.org)

Vi as an OpenACS IDE

Created by OpenACS community, last modified by Monika Andergassen 05 Oct 2015, at 12:45 PM

In vim add the following in your .vimrc will help convert tabs to 4 spaces to meet part of the OpenACS coding standard.

set tabstop=4
set expandtab
set list
set listchars=tab:>.

It's also nice to have syntax highlighting by adding the following line

syntax on

Also useful to use tagging features. In brief - run ctags -R in the root of the install or source tree.

At that point you can edit using vim -t procname or ::package::procname and go to the corresponding place in the code. From within the code, you can lookup functions by having the term highlighted and hit CTL-] - use CTL-T to go back.

Only works if you edit from the top directory, all tags are relative to there.

References to this Page: en:docs-dev-tutorial, en:docs-eng, en:coding-standards-index, en:Documentation_Project_Plan, en:docs-eng-toc Categories: Subsystems Documentation (OpenACS.org), Tutorials for Programmers (OpenACS.org), Coding Standards (OpenACS.org)