User Interface Guidelines

Author: Marc-Aurèle DARCHE
Revision: $Id$

Contents

1   Ergonomics/Usability/Accessibility

1.1   Ergonomics/Usability

The default behavior of CPS should be what most users and clients expect from this kind of product.

1.2   Accessibility

Accessibility is about making content usable. Accessibility benefits everyone and in particular has benefits for:

  • other devices such as personal assistant, web-phones, news readers, etc.
  • blind people
  • old people
  • people with any kind of disabilities
  • people who don't have any disabilities, yet

One should read http://diveintoaccessibility.org/ to have a precise idea about what accessibility and interoperability are. "Dive into accessibility" is available in many languages: http://diveintoaccessibility.org/translations.html The site http://openweb.eu.org/ [fr] is also a must read, but only available in French.

If you want to follow the improvements of CPS accessibility, you can read and participate in the CPS Accessibility task list.

1.3   Laws

Laws in Europe (including France) and the USA require that government web sites are accessible.

In Europe:

XXX: Provide text of the European law

In France:

La loi n°2005-102 pour "l'égalité des droits et des chances, la participation et la citoyenneté des personnes handicapées" a été adoptée en France le 11 février 2005. L'article 47 stipule : "Les services de communication publique en ligne des services de l'Etat, des collectivités territoriales et des établissements publics qui en dépendent doivent être accessibles aux personnes handicapées".

In the USA:

XXX: Provide text of the USA law

1.4   WAI Conformance

CPS accessibility is evaluated against the Web Content Accessibility Guidelines 1.0 because this is the internationally recognized standard regarding accessibility. The Web Content Accessibility Guidelines 1.0 defines 3 levels of accessibility:

  1. Conformance Level "A"
  2. Conformance Level "Double-A"
  3. Conformance Level "Triple-A"

CPS WAI conformance in general is difficult to evaluate because CPS is composed of so many products, many being optional and some with not so good accessibility.

Some products are not accessible at all because some customers still at times explicitly ask for non-accessible functionalities.

So, we will state what sets of CPS products and configurations should be used to achieve WAI-A, WAI-AA and WAI-AAA conformance respectively.

1.5   Conformance Level "A"

CPS is WAI-A compliant when composed of the following products:

Note that at the bottom of the page of a stock CPS there is a blue icon stating the WAI-A conformance.

New developments to CPS must not break the WAI-A compliance of CPS.

1.6   Conformance Level "Double-A"

CPS could easily be made WAI-AA compliant when composed of the following products:

But it will be necessary to:

  • Set the tableless option to the pages defined in the CPSSkins themes.

    (Portal Themes -> Go to the used theme -> Go to the used pages -> Edit on the page tab-> General -> Select Tableless)

  • Fix Ticket #495: Document HTML view page should contain HTML metadata.

1.7   Conformance Level "Triple-A"

CPS can be made WAI-AAA compliant, but at this time do so requires some specific work.

2   XHTML

2.1   General

CPS follows the DTD XHTML 1.0 Strict:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

Developers and web designers should code and use CPS according to this definition.

2.2   Checkpoints

  • Check the validity of your XHTML pages

    1. You can check directly against the W3C HTML validator http://validator.w3.org/.

    2. You can use the webdeveloper toolbar (version 1.0.1 or up) for Firefox:

      Tools -> Validate Local HTML
      

      This is particularly interesting if your page is not readable from the outside (for example because of a firewall).

  • Unneeded markup shouldn't clutter the HTML output.

    Check that your templates don't produce useless <div> and <span> elements. Also, do not over-use the <div> elements to position "class" attributes everywhere.

    Finally do not use <div> elements where you should have semantically used <p> elements.

  • <img> element should have an "alt" attribute:

    <img src="logo_cps.png" alt="CPS logo"/>
    
  • Try to avoid using inline CSS properties:

    Avoid to use the "style" attribute for lazy-styling your HTML elements. This makes it difficult to customize your macros, templates and pages later on.

    In conjunction with JavaScript, the use of such markup might be legitimate:

    <div class="tooltipArea" style="visibility: hidden;">
    </div>
    
  • All web pages should have a <h1> element.

    A web page cannot have a <h2> element without first having a <h1> element.

    A web page cannot have a <h3> element without first having a <h2> element, etc.

  • Don't use presentational elements and attributes in your code such as <b>, <i>, <center>, border="0". CSS properties take care of that.

  • <table> is good for tabular data, matrix-like data, forms and some kind of listings.

    Avoid as much as possible the use of <table> markup for layout purposes.

    In a complicated layout case, table layout may be bad, but the only solution, so one cannot totally exclude the use of tables for layout purpose at this time.

    But, one can always use tables without any align, valign, or border kind of information. All those can be safely and cleanly specified through CSS.

  • Make your <table> semantic.

    • Specify the summary attribute for your <table>:

      <table summary="A table listing the available events and their notifications in this context">
      
    • Use <thead>, <tbody> and <th> elements whenever possible.

    • Specify column names whenever possible.

    • Example of a table used for a form (note the use of the <th> and <td> elements and that the button is not enclosed in the <table>):

      <form id="loginForm" action="/logged_in" method="post">
      
        <table id="login" class="form" summary="Table for entering login information">
          <tbody>
          <tr>
            <th>
                <label for="username">User name</label>
            </th>
            <td>
                <input id="username" name="__ac_name" class="focus" size="20" value="manager" type="text"/>
            </td>
          </tr>
          <tr>
            <th>
                <label for="password">Password</label>
            </th>
            <td>
                <input id="password" name="__ac_password" size="20" value="" type="password"/>
            </td>
          </tr>
          <tr>
            <th>
                <label for="remember">Remember my name</label>
            </th>
            <td>
                <input name="__ac_persistent" checked="checked" id="remember" class="noborder" type="checkbox"/>
            </td>
          </tr>
          </tbody>
        </table>
      
        <p class="buttonArea">
          <button type="submit">Login</button>
        </p>
      
      </form>
      
    • Example of a table used for tabular or matrix-like data (note the use of the <thead> and <th> elements):

      <table class="history listing" summary="Action history list">
        <thead>
          <tr>
            <th>Date</th>
            <th>Action</th>
            <th>Revision</th>
            <th>Author</th>
            <th>Comments</th>
          </tr>
        </thead>
        <tbody>
          <tr class="even">
            <td>01/19/2006 11:23 AM</td>
            <td>
              Modification
            </td>
            <td>
              Revision 2
              Language English
            </td>
            <td>CPS Manager Manager</td>
            <td></td>
          </tr>
          <tr class="odd">
            <td>01/19/2006 11:23 AM</td>
            <td>
              Commit of this revision
            </td>
            <td>
              Revision 2
              Language English
            </td>
            <td>CPS Manager Manager</td>
            <td>Validating the revision.</td>
          </tr>
          <tr class="even">
            <td>01/19/2006 11:22 AM</td>
            <td>
              Creation of a revision
            </td>
            <td>
              Revision 1
              Language English
            </td>
            <td>CPS Manager Manager</td>
            <td>A new revision of this document.</td>
          </tr>
          <tr class="odd">
            <td>01/19/2006 11:22 AM</td>
            <td>
              Creation
            </td>
            <td>
              Revision 1
              Language English
            </td>
            <td>CPS Manager Manager</td>
            <td></td>
          </tr>
        </tbody>
      </table>
      
  • Include <input> elements and <form> content inside <p>.

    This is required by the XHTML 1.0 Strict DTD:

    <form method="get">
      <p>
        Blah blah.
      </p>
      <p>
        <button type="submit">Checkin</button>
        <button onclick="history.back()">Cancel</button>
      </p>
    </form>
    
  • Associate labels explicitly with their controls.

    In other words use <label> along with your <input type="text"/>, your <input type="checkbox"/> and your <input type="radio"/> elements. Using labels makes it possible to use the mouse pointer on the label (clicking on the label) to active the input element, so that it is easier to select a text input, a check box or a radio box, just like it is in heavy client applications such as Firefox.

    Example:

    <label for="firstName">First name:</label>
    <input type="text" name="firstname" id="firstName"/>
    

    Cf. "Labeling form controls": http://www.w3.org/TR/WCAG10-HTML-TECHS/#forms-labels.

  • Use the "id" attribute to provide a relative location URL instead of the old <a name="xxx"/> markup. This is needed to do the transition to XHTML1.1. Example:

    <p>
      Check the <a href="#subject">subject headings</a>.
    </p>
    
    <h3 id="subject">Subject</h3>
    <p>
      Blah blah.
    </p>
    
  • Structure your text into paragraphs using <p>. To create paragraphs do not use <br/><br/>.

    Example:

    <p>
      Blablah
    </p>
    <p>
      Blablah
    </p>
    <p>
      <input type="checkbox" name="item1" id="item1" value="xxx"/><label for="item1">Item1</label><br/>
      <input type="checkbox" name="item2" id="item2" value="yyy"/><label for="item2">Item2</label><br/>
      <input type="checkbox" name="item3" id="item3" value="zzz"/><label for="item3">Item3</label><br/>
    </p>
    
  • Do not put spaces in strings -- Write:

    action="string:foo" (without space)
    

    NOT:

    action="string: foo"
    

    which produces a link <a href=" foo"> which is a malformed URI.

    Example:

    action="string:foo"
    
  • Use the <button> element instead of the <input type="submit"> or <input type="button"> markup. The <button> markup is more semantic and cleanly separates the value of the button from its label. This is very clean and practical, especially for localized user interfaces. Separating the value from the label is not possible when using the <input> markup.

    Example:

    <form>
      <button name="action" value="copy" type="submit">Copy</button>
    </form>
    
    <form>
      <button name="action" value="copy" type="submit"
              i18n:translate="button_copy">Copy</button>
    </form>
    
  • The value of the method attribute of the form element must be lower case. Examples:

    <form method="get">
      <p>
      </p>
    </form>
    
    <form method="post">
      <p>
      </p>
    </form>
    
  • Avoid the target attribute, as it conveys layout information. But, if you do use this attribute anyway, its value must be a single token. For example, use:

    <a target="external_link">
    

    NOT:

    <a target="external link">
    

3   CSS

3.1   General

Sample CSS code:

.tooltipArea {
  color: #000000;
  background: #ffffe1;
  padding: 0.8em;
  font-weight: normal;
  font-size: 80%;
  text-align: left;
  visibility: hidden;
  display: none;
  z-index: 1000;
}

Here are the main aims in these CSS guidelines:

  1. Everybody follows the same conventions, so the code is clean and easy to read.
  2. There is not too much lost space.
  3. Diffs should be rare and easy to read
  4. Sizes are proportional so that the defined layout is "elastic" (scalable), diffs which is essential for accessibility

Basically those guidelines are what can be found in the CSS specs of the W3C, though they put everything on the same line if there is only one property that is used, but this is not practical if we want to diminish the occurrence of diffs.

3.2   Checkpoints

  • Check the validity of your CSS stylesheets

    1. You can check directly against the W3C CSS validator http://jigsaw.w3.org/css-validator/.

    2. You can use the webdeveloper toolbar (version 1.0.1 or up) for Firefox:

      Tools -> Validate Local CSS
      

      This is particularly interesting if your site is not readable from the outside (for example because of a firewall).

  • Indentation width of 2 characters inside parentheses.

  • No space before the ":" character and 1 space after.

  • One property definition per line.

  • The names of the Ids and classes should be written in mixed case, for example "div.contentTabs", "div.bookPageHeader", "#idioma", "#byline", etc.

  • The names used for selectors, that is the values of id and class attributes of the HTML elements, should not contain any "_" characters. (the first CSS standards did not allow the "_" character so old browsers like Netscape 4.x choke on them).

  • Use the "em" unit instead of the "px" and "pt" units whenever possible. The "em" unit is a proportional unit that scales according to the font size, so all the sizes specified in "em" will grown or shrink as the user asks her browser to increase or decrease the size of the text. This is essential for accessibility.

  • Write the color codes in lowercase and in their full 6 digits hex notation. Examples: #ffffff, #98a2b9, etc.

  • It is possible and valid to specify more than one class for an HTML element. Example:

    <table class="history listing" summary="Action history list">
      <thead>
     ...
    
  • For CSS code generated through DTML, for example using <dtml-with stylesheet_properties>, the variable substitutions should be done by using <dtml-var color> and not &dtml-color; because HTML escaping is not to be done in CSS files.

    Sample CSS code using DTML variables:

    div.contentTabs a:hover {
      background: #ffffff;
      color: #000000;
      border-color: <dtml-var bordercolor>;
    }
    

3.4   CSS dirty hacks

All the main and default CSS files should only contain valid and clean CSS properties and directives. The main and default CSS files should not contain any CSS dirty hacks. That is, for example, hacks to counter the buggy Microsoft Internet Explorer (MSIE) box model, the MSIE hover bugs, the MSIE 6 peekaboo bug, etc.

All tricks to circumvent MSIE specific bugs should go into dedicated files. To achieve this use the MSIE Conditional Comments. MSIE Conditional Comments are proprietary instructions that do not interfere with W3C standards and that make it possible to avoid the many bugs of MSIE.

Examples:

<!--[if IE 5.5]>
<link rel="stylesheet" type="text/css" href="msie-5.5.css" media="screen" />
<![endif]-->

<!--[if IE 6.0]>
<link rel="stylesheet" type="text/css" href="msie-6.0.css" media="screen" />
<![endif]-->

So our CSS are kept clean and when MSIE bugs are fixed, or more probably when nobody uses MSIE anymore, those msie.x.y.css files can simply be removed from our products.

Note that MSIE 5.0 and MSIE for Mac are not to be supported. Rationale: nobody uses MSIE 5.0 anymore or they should update it to a newer version for the sake of security updates anyway. As for Mac users they would be stupid to use MSIE while they have Safari, Mozilla and Firefox available for their platform.

Every hack should be well commented, and a URL referencing the source of the hack should be provided.

4   JavaScript

JavaScript can provide usability enhancements and can also be used to decrease some server-side processing. But JavaScript should not be required on the client-side to have a functional web site and usable functionalities.

4.1   Use available frameworks and libs

CPS ships with the Prototype framework and the script.aculo.us library :

  • Prototype: features an easy-to-use toolkit for class-driven development a a nice Ajax library
  • script.aculo.us: is based on Prototype

Every JavaScript code in CPS should use the higher level API that those shipped frameworks and libs provide. This results in code easier to understand and maintain.

For details on how CPS is AJAX-ified read:

1. CPS ajaxification round #1

2. CPS ajaxification round #2

3. CPS ajaxification round #3

4. CPS ajaxification round #4

4.2   Accessibility

A too heavy use of JavaScript clearly conflicts with accessibility. A too heavy use of JavaScript also clearly produces code harder to maintain and debug.

It should be possible to visit, search, create/modify documents, and navigate through the web site using a browser without JavaScript support or with JavaScript disabled.

Accessibility is of a prime concern for the front-office, since most of the visitors and users of a web site use the front-office. Accessibility for the back-office is less important, but is still something developers should care about.

Back-office management such as graphic decoration, color choosing, layout setting, are already very visual concepts, and thus are not very accessible by their very nature. Using JavaScript for such a back-office use is allowed. This is what CPSSkins does.

5   Image formats

The main format to use is PNG.

For all the products one should use images in the PNG format, because:

When it comes to landscape and photo-like style of pictures, PNG is not the best suited image format, in terms of compression. In this case one could use the JPEG format. But landscape and photo-type images are usually seldom found in CSS and user interface skins. Landscape and photo-type images are more often present as web site contents.

5.1   Tools

Web design and graphic customization done on top of CPS are often delegated to web designers and graphic designers who might not know well the PNG format. The main reason for this is that most of them use Adobe Photoshop, and that Photoshop has poor PNG support. Photoshop doesn't compress PNG effectively and handles gamma correction weirdly. The PNG format has many compression levels (remember, lossless compression), from 0 to 9, but Photoshop only compresses up to 6.

So web designers and graphic designers should be advised to either use the GIMP, use a Photoshop plugin or use external utilities:

5.2   PNG vs GIF

All browsers supports PNG, except Microsoft Internet Explorer (MSIE) that only supports it partially. But contrary to the general belief concerning Microsoft Internet Explorer flaws, it is very possible to use PNG in place of GIF.

Here is a why:

  • GIF describes images with a 256 indexed colors scheme.
  • PNG can describe images by using either an RGB 16 million colors scheme + alpha channel, or a 256 indexed colors scheme.
  • MSIE knows how to display GIF, RGB PNG without alpha channel or indexed PNG with optionally a transparency color (just as for the GIF).

So with the current state of MSIE, it is possible to advantageously replace all the GIFs (even with transparency) by PNGs. The only situation where GIFs cannot be replaced systematically by PNGs, is when the GIFs are animated GIFs. This is not a common situation. There is a PNG equivalent, the MNG, but very few browsers support it yet.

5.3   Technical details: The alpha channel

It is still possible to use PNG RGB + alpha channel with MSIE if:

  • One uses a specific MSIE behavior to enhance its native PNG support. For example CPS and CPSSkins ships with the following PNG behavior (but it is disabled by default): http://webfx.eae.net/dhtml/pngbehavior/pngbehavior.html
  • One takes care to create with the GIMP the background layer of the image with the same color as the background color of the web page the image will appear in. Enable the "save the background color" option.

6   Translation recommendations

6.1   Checkpoints

  • Use <tal:block> or <label> for translation strings, not span.

    Use:

    <tal:block i18n:translate="msgid">A meaningful translation</tal:block>
    

    Or:

    <label i18n:translate="msgid">A meaningful translation</label>
    

    and NOT:

    <span i18n:translate="msgid">blah</span>
    

    because it produces:

    <span>msgstr</span>
    

    with useless <span> elements that needlessly encumber the HTML output.

  • Beware of empty <label>:

    <label i18n:translate="msgid" />
    

    produces:

    <label />msgstr
    

    To produce <label>msgstr</label> one must write:

    <label i18n:translate="msgid">A meaningful translation</label>
    
  • Provide a meaningful translation message example in the template.

    Example:

    <tal:block i18n:translate="msgid">A meaningful translation</tal:block>
    

    and NOT:

    <tal:block i18n:translate="msgid"/>
    

    because a meaningful translation will help translators later on.

6.2   Recommendations for .po translations

Guidelines:

  • About using HTML in translation files:

    Attempt to not put HTML in translations and thus in .po translation files. There are exceptions though, for example for the "welcome_body" msgstr. But do not put color information or any other layout information in .po files. Having something like <h1><font color=#ff0000> is wrong.

    Translators, please note that CPS uses XHTML and thus it is intentional that the HTML markup in the .po files is lower case.

  • Respect language specific punctuation.

    Example: ":" should be preceded by an unbreakable space in French, but not in English.

  • Use proper capitalization.

    Example: Only the first word of each sentence is capitalized in French. In English too, except for newspaper headlines (I believe). Anyway, choose a consistent style and use it consistently.

  • Be consistent in the use of ":".

  • Group msgids by area.