WebGUI Templates HQ

General

• All HTML must validate as XHTML 1.0 Strict.
• Use standard tags whenever possible. Tags should be used in a semantic way. For example <quote> instead of <p class="quote">.
  
• Keep the templates simple; make them in a way that they look decent without any css. The document flow should be logical.
• A functionality that is in more than one template should use the same vars and html in all those templates. Examples are pagination, asset controls, attachments, file icons etc.
  
• Add indents and comments to add more structure to the code, this is especially important for closing tags of the same type (e.g. </div></div>).
• Remove inline styles and other deprecated markup.
  

Basic tags

Headers (h1, h2, ...)

All asset title headers in templates should be h3. Exceptions are the Style (the site name is in a h1) and Page Layouts (h2). H2's should also be used in operation templates, account layouts etc.

Any other headers inside the template should have the correct hierarchy. So, in summary:

• h1: sitename in style template
• h2: page layout title, titles in operation templates (e.g. "Login") or other templates for things that do not live on a page
• h3: asset title
• h4 – h6: asset sub titles

Table, tr, td, th, thead, tbody etc.

Remove all table layout that is used for positioning. When use of a table is appropriate, column names should be in th tags (in a thead).

The only attribute on a table tag should be cellspacing="0". Use the __ODD__ variable when a table is in a loop to add a class to the odd trs:

<tr<tmpl_if __ODD__> class="odd"</tmpl_if>>
  <td>...</td>
</tr>

Use caption, thead, tbody, tfoot and colgroup when appropriate.

Divs

Every element should be contained in a div with a class for easy positioning (e.g. Attachments, description, thread menu), but beware of  “divitis”, keep it balanced.

Every template should have a containing div, with and id, and class:

<div id="[asset name]<tmpl_var assetId>" class="[asset name] [template name]">
...
<!--/[asset name]<tmpl_var assetId> /[asset name] [template name]-->
</div>

Descriptions should always be in a div w/ class “description”. Close divs with a comment, e.g.

<div class=”description”>
  ...

<!--/decription-->
</div>

Note: to prevent bugs in IE (repeating text - usually triggered by floats) the comment comes before the closing tag.

B, i, strong, em and span

Do not use b, i, strong or em for markup, unless they are used in a semantic way (e.g. an error message could contain a strong). Use span for styling inline elements.

Ul, ol and dl

Use the appropriate type of list for listed items: search results in a dl, link lists in an ul etc.

P

Use the p tag for a paragraph of text only, for example for wrapping a synopsis. Since text is usually generated by the editor, p tags included, p tags should be scarse in templates.

Br

Do not add breaks, spacing and newlines should be done with css by the designer.

Form, fieldset, legend, input, select, optgroup, textarea, label etc.

A specification for forms is in the works.

Hr

Don't use hrs, since cross browser markup is difficult.

Img

Images should have an alt attribute with descriptive content. An image url or filename is not descriptive. Use the asset title when possible (like in Article with Image) or add an RFE when there is no way of adding a proper alt content (and sometimes: improvise).

Blockquote, q

Use blockquote or q for quotes (for instance for quotes in the collaboration system).

Classes and IDs

• CSS should be valid CSS2.1
  
• Classes and IDs should be semantic/decriptive.
• Don't add IDs unless they are unique (wrong: id="article", right: id="article<tmpl_var assetId>").
• Keep it simple: do not add classes to elements that can easily be targeted with use of their parent.
• Use classes that are already in other templates, if the element has the same function. Find common elements and standardize classes and IDs. e.g. buttons, pagination, success and error messages.
• Styles for those elements should be added to wg-core.css; classnames and IDs should be preceded by "wg-" (e.g. "wg-attachmentIcon").
• Use camelCase for classes and IDs consisting of multiple words.

• Inline styles should be removed and added to a stylesheet, one stylesheet per asset (not one per template). This stylesheet should have the same name as the asset (e.g. article.css) and should be included in the head block of the tempalte, using the link tag.
• Do not make this css very specific, overriding should be easy. For instance you should not use ID selectors (#) and no long rows of combined selectors.
  
• Styles that are used by more than 1 asset (pagination, inline icon), should be added to wg-core.css.
• Only styles for positioning should be included, and only if necessary (i.e. the functions of the asset are not clear without it).
• If you do need a fill color, use black or grey (e.g. for tableheaders).
• IE versions can be targeted with divs which are included in the style template with conditional comments.
• Float clearing: anticipate the clearing of floats. If there is no element that can be used for clearing, add <div class="wg-clear"></div> Note: we are not using a br for this, because of possible IE bugs.
  

1. Empty loops should generate no html. Empty lists, tables or other tags should be avoided. Like so:
   

   <tmpl_if item_loop>
     <ul>
       <tmpl_loop item_loop>
         <li>...</li>
       </tmpl_loop>
     </ul>
   </tmpl_if>
   

   The above is usually the best way, but __FIRST__ and __LAST__ can be used when appropriate.
2. Fix/add a bug report for template variables that are incorrect or not working.
3. File RFEs for inconsistent use of variables. For example: the attachment loop in the article template differs from the one in the collaborations system.
   
4. Pay attention to i18n: is everything internationalized? If not, add an RFE.
5. HTML and template code should be properly nested. When you use tmpl_if or tmpl_unless, you should check if HTML is still valid if that condition doesn't apply. Mistakes like this one, for example, are easy to miss (when your code is complex):

   <tmpl_if user.canEdit>
     <p>
     <a href="">edit</a>
   </tmpl_if>
   
   <tmpl_if user.isModerator>
     <a href="">delete</a>
   </tmpl_if>
   
   </p>

Unobtrusive Javascript

First of all, keep your Javascript seperated from your Html. Just like CSS Javascript should be put in an external file and linked to the Html page in the head tags like this:

<script type="text/javascript" src="scripts.js"></script>

If you have a special reason to use inline script tags, you should start with a CDATA tag:

<script type="text/javascript">
  //<![CDATA[
  ...
  //]]>
</script>

Also, make sure you use Javascript as an enhancement rather than a necessity.
IE. If you want to post a form, make sure it will also be submitted if the user doesn't have Javascript turned on.

DO

HTML:

<form action="checkForm" onsubmit="return checkform(this)">
    <p>
        Login: <input type="text" name="login" id="login" />
        <br />
        <input type="submit" value="send" />
    </p>
</form>

Javascript:

function checkform(form) {
    var error='';
    error += f.login.value == '' ? 'login' : '';

    if (error!='') {
        alert('Please enter the following:' + error);
    }
    
    return error=='';
}

DON'T

HTML:

<form action="checkForm">
    <p>
        Login: <input type="text" name="login" id="login" />
        <br />
        <input type="button" onclick="checkform(this)" value="send" />
    </p>
</form>

Javascript:

function checkform() {
    var f = document.forms[0];
    var error = '';
    error += f.login.value == '' ? 'login' : '';

    if (error!='') {
        alert('Please enter the following:' + error);
    }
    else {
        f.submit();
    }
}

If the user has Javascript disabled, the form won't be submitted because it doesn't trigger the checkform function and the button isn't set as a submit button.

T.b.a.