Web Standards Document

CIBO

Revision History
12.10.2010 Created 1.10.2011 Changes to XHTML to HTML5 doctype 1.26.2011 Changes to HTML5 use; removed accessibility section 1.27.2020 Adding JavaScript validation and CSS font sizing percentages; added browser testing and operating system list

Introduction
This document contains recommendations for the use of HTML5 and Cascading Style Sheets (CSS) where HTML5 structure is separated from the CSS style and layout of a document. As a set of standards it aims to inform and assist front-end developers in the creation of consistent, maintainable, high quality code.

HTML5
Introduction
HTML5is the new version of HTML4, XHTML1, and DOM Level 2 HTML. The following set of guidelines can be used to assure compatibility with HTML5. They are a distilled version of the recommendations contained within the W3C document on HTML5: http://www.w3.org/TR/html5/.

HTML5 Basics and Tag Rules

We will not using the following HTML5 tags: <header>, <nav>, <article>, and <section> for browser compatibility reasons. HTML5 allows for HTML or XHTML style syntax and we will use the XHTML style syntax. 1. Documents must be well formed 2. Tags and attributes must be in all lowercase 3. For non-empty tags (<a>, <td> and <p>, for example), end tags are required 4. Attribute values must always be quoted 5. Attribute minimization is not supported 6. Empty elements (<hr> and <br>, for example) must be properly closed 7. The id attribute must be used instead of the name attribute 8. All images must have alt attributes Documents must be well formed Essentially, this means that all HTML elements must be closed and must nest properly. Proper nesting is as follows: CORRECT: <p>Here is an emphasized <em>word</em>.</p> INCORRECT: Elements overlap <p>Here is an emphasized <em>word.</p></em>

Empty elements must either have an end tag, or the start tag must end with />. For example, XHTML would use <br/> or <p></p>.

CORRECT: Minimized tag syntax with white space <br /> INCORRECT or UNPREDICTABLE RESULTS: <br/> or <br></br> Element minimization and empty element content Given an empty instance of an element whose content model is not empty (e.g., an empty div or paragraph), do not use the minimized form. For example, use <div id="divName"></div> for a div with no content, not <div id="divName" />. An exception to this rule is <textarea> which must always have an end tag i.e. <textarea></textarea> Attribute values must be quoted All attributes must be quoted, even simple numeric values. Attribute minimization is not supported In XHTML, attribute-value pairs must be written in full. HTML supports certain attributes where no value is provided, but this is not allowed in XHTML. CORRECT: Unminimized attributes <dl compact="compact"> <option value="1" selected="selected"> INCORRECT: Minimized attributes <dl compact> <option value="1" selected> Line breaks and attribute values Avoid line breaks and multiple whitespace characters within attribute values. User agents do not handle these consistently. Use name and id attributes XHTML treats id and name attributes differently than HTML 4. Without going into the specifics, the id attribute is preferred in XHTML (name is actually deprecated in favor of id). Many HTML clients don't play well with id attributes, so supply both name and id to ensure compatibility: CORRECT: Identification with id and name <form name="foobar" id="foobar" action="action.pl"> </form> UNPREDICTABLE RESULTS: Identification with name only <form name="foobar" action="action.pl"> </form>

Element prohibitions XHTML places restrictions on the nesting of elements. Certain elements cannot contain other elements. The following restrictions apply to all depths of nesting: a: Cannot contain other a elements. pre: Cannot contain the img, object, big, small, sub, or sup elements. label: Cannot contain other label elements. form: Cannot contain other form elements. Entities Some characters are part of XHTML, e.g. the character for 'less than' is < . To display these characters we must insert character entities in the XHTML source. For example: Less than (<) has to be written as either &lt; (entity name) or &#60; (entity number).

Validity
The W3C validator can be found at http://validator.w3.org/. You may also use browser plugin or various code editors that have HTML validators.

HTML5 Structure/Formatting
General Recommendations
Be consistent Throughout your code, follow a consistent treatment of indentation, commenting, and case usage. Conform to the appropriate standards Follow the XHTML standard as much as possible. Deviate from the standard only with sufficient justification. All deviations from standards, either in this document or in others, must be documented for each project. Write code that can be read quickly and easily Even though XHTML is not a spoken language, well-written code can still be read to a degree. Write code to maximize its readability.

Code indentation
Indent code to enhance readability Code indentation is a way of greatly enhancing code readability. By indenting sections of code based on their function, or by the degree of nesting, it will be easier to read and understand a piece of code. Indent using tabs Indent using tab characters, as opposed to white space. This will ensure consistency across files and increase editing efficiency. Text editors such as Dreamweaver allow the user to specify how many white space characters make up one tab. This is usually set to 4 spaces. Indent all nested blocks of code Code fragments that necessarily reside inside parent tags should be indented. For every level of nesting, indent the code one tab further. Tables are the cleanest example of nested blocks of code, but there are other instances where this occurs. The following example with several nested div tags should provide guidelines: <!-- Nested DIV elements --> <div> <p>A little indentation of nested blocks </p> <div> <img src="indented.jpg" width="1" height="1" alt="Boo"> </div> </div>

Comments
Descriptive comments These are comments whose purpose is to describe functionality, or to clarify the thinking behind a certain section of code. A simple comment or comment block should be used for descriptive comments: Simple Descriptive Comment <!-- Simple comment --> <!-Comment block (1) Comment block (2) Comment block (n) --> Structural comments Descriptive Comment Block

These are comments whose purpose is to delineate a region of code with a clear beginning and ending. For these comments, use an initial comment before the block, and a closing comment after the block. The format should be as follows: Structural Comment Layout <!-- BEGIN element --> . . . <!-- END element --> OR </div><!--// #id or classname -->

Comment all-important blocks of code Add comments to help explain all-important blocks of code. Major modular code blocks (e.g., <div>) or functional elements (e.g., <form>) are strong candidates. Descriptive comments are suitable unless the block of code is sufficiently long, in which case structural commenting should be used. Use comments to indicate major page elements If a page layout contains several key regions, indicate the code used to markup these regions. For example, for a page that has primary navigation along the top of the page, and secondary navigation in the left column, comment each of these sections of XHTML using the structural format above. Use comments wisely At some point, comments begin to degrade readability, as well as performance. Use them wisely. Nesting Comments If comments are nested, also indent them, but elements should not indent from comments above them. Example: <!-- BEGIN something --> <!-- Nested DIV elements --> <div> <p>A little indentation of nested blocks </p> <div> <img src="indented.jpg" width="1" height="1" alt="Boo"> </div> </div> <!-- END something -->

Document Template
DOCTYPE
The DOCYTPE declaration used for every HTML5 document is: <!DOCTYPE html>

CSS Imports
Use external style sheets and not inline styling. There are two methods of referencing external stylesheets: Using linked stylesheets <link rel="stylesheet" type="text/css" href="/css/style.css" title="Alternate Style Sheet" /> Using the @import rule <style type="text/css" media="all" >@import "/css/style.css" /> Common areas of functionality should be split into appropriately named imported stylesheets. e.g.. styles for links, forms and buttons would be imported as: <style type="text/css" media="all" > @import "/css/links.css" @import "/css/buttons.css" @import "/css/forms.css" </style> See section on Cascading Style Sheets for more details on CSS imports.

JavaScript Includes
Any JavaScript to be used should be 'included' to allow easier code and document management: <script language="javascript" type="text/javascript" src="/js/main.js"></script> Example structure of an HTML5 page <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" />

<title>Layout 1</title> <link rel="stylesheet" type="text/css" href="css/style.css" /> </head> <body> </body> </html>

CSS
Usage
Cascading Style Sheets (CSS) give the author of an HTML5 page the ability to separate the styling and layout elements from the structure and content of a document. They are of fundamental importance to the usability of a page for everyone.

Indentation & Formatting

Stylesheet rules should be formatted as follows, with indentation (using tabs) for clarity: .styleName1 { attribute1: value1; attribute2: value2; . . attributeN: valueN; } .styleName2 { attribute1: value1; attribute2: value2; . . attributeN: valueN; }

Compliance and validity

All CSS code must be compliant according to the W3C recommendation: http://www.w3.org/TR/REC-CSS2/ A CSS validator should check validity http://jigsaw.w3.org/css-validator/ Certain code editors also have built-in CSS validators.

Imports
All CSS must be contained in files external to the main HTML5 page. No inline styling should be used. <link> and @import are the two methods used to reference the CSS from within the <head> tag of an HTML5 page. <link> is declared first, usually to reference an accessible, alternative stylesheet that will provide a browser friendly version for non CSS2 compliant browsers. The @import method references stylesheets for CSS2 compliant browsers and will override the CSS rules in the <link> stylesheet. For example: <link rel="stylesheet" type="text/css" href="/css/style.css" title="Alternate Style Sheet" /> <style type="text/css">@import "/css/style.css" />

Naming conventions
Use descriptive class names and camel-case Create class names that have context and are meaningful to the page elements that they apply to, or to the styles that they represent. Use camel-case for names containing multiple words. For example: div.paginationTitle { } div.crumbTrailLink { }

CSS Rules
CSS selectors are used to apply CSS rules to HTML5 elements. Type selectors A type selector matches every instance of the element type in the document tree. For example: The following rule matches all h1 elements in the document tree:

h1 { font-family: sans-serif; } Class selectors For all elements with a class attribute you can assign style information to those elements. For example: .errorText { color: red; } would style the following text red: <div class="errorText">Error text copy</div> ID selectors Use the ID attribute instead of class for CSS rules that are applied only once on a page. For example: #leftNavigation { width: 100%; } <div id="leftNavigation"></div> This rule will only match an element that has an ID value of "leftNavigation".

Inheritance Children in the document tree can inherit CSS values. This would mean, for example, that if no color has been assigned to a class applied to the <p> element then it would inherit the color of its parent elements: CSS: body { font-size: 100%; color: #000000; }

p{ font-size: 80%; } p.footerText { font-weight: bold; } HTML5: <body> <p class="footerText">Paragraph of footer text...</p> </body> The text above inherits font-size from its parent (<p>) and color from its grandparent (<body>) yet maintains its font size. Multiple class inheritance This is useful for applying styles from different classes without declaring a new rule. For example (following on from the above example): CSS: p.footerText a { color: #CCCCCC; } HTML5: <body> <p class="footerText">Paragraph of <a href="footerLink.html">footer</a> text...</p> </body>

CSS Reset
A CSS file will contain a reset, font normalization and base styles. The goal of the CSS reset file is to remove browser specific styles and then use the main global CSS file to build the CSS from scratch so that elements will appear the same in all browsers. Font sizing percentages:

10px = 77% 11px = 85 12px = 93 13px = 100 14px = 108 15px = 116 16px = 123.1 17px = 131 18px = 138.5 19px = 146.5 20px = 153.9 A full list of the font size percentages: http://developer.yahoo.com/yui/3/cssfonts/.

CSS Hacks
Hacks can be used but as a last resort. The issue with hacks is that they are not future proof. A future browser (perhaps IE9 or later) could potentially use a hack for IE7. Example: p{ color: red\9; /* IE8 and below */ *color: green; /* IE7 and below */ _color: blue; /* IE6 */ }

CSS Conditional Comments

Conditional comments should only be used if absolutely necessary. Multiple stylesheets can be confusing and add extra requests. Example: This would be placed between the <head> tags. Target IE6 <!--[if IE 6]> <link rel="stylesheet" type="text/css" media="screen,projection" href="css/ie6.css" /> <![endif]--> Target IE7 <!--[if IE 7]>

<link rel="stylesheet" type="text/css" media="screen,projection" href="css/ie7.css" /> <![endif]--> Target IE8 <!--[if IE 8]> <link rel="stylesheet" type="text/css" media="screen,projection" href="css/ie8.css" /> <![endif]--> Target IE 6 and LOWER <!--[if lt IE 7]> <link rel="stylesheet" type="text/css" href="ie6-and-down.css" /> <![endif]--> or <!--[if lte IE 6]> <link rel="stylesheet" type="text/css" href="ie6-and-down.css" /> <![endif]--> Target IE 7 and LOWER <!--[if lt IE 8]> <link rel="stylesheet" type="text/css" href="ie7-and-down.css" /> <![endif]--> or <!--[if lte IE 7]> <link rel="stylesheet" type="text/css" href="ie7-and-down.css" /> <![endif]--> Target IE 8 and LOWER <!--[if lt IE 9]> <link rel="stylesheet" type="text/css" href="ie8-and-down.css" /> <![endif]--> or <!--[if lte IE 8]> <link rel="stylesheet" type="text/css" href="ie8-and-down.css" /> <![endif]-->

JavaScript
Usage
JavaScript should only be used to enhance the user experience. Accessibility can be restricted when JavaScript is used in the functionality of an HTML5 page as cross browser support is varied and users may have JavaScript disabled.

Indentation & Formatting

As with the recommendations for HTML5 authoring, formatting conventions with JavaScript are aimed at facilitating the creation of clean, readable code. Use semicolons to terminate all statements JavaScript does not require the use of semicolons to terminate statements, but it is a good rule to follow. Enclose all control structure statements within braces Braces are used in JavaScript to delineate blocks of code to be executed. Use them for all control structures, even if there is only one statement to be executed. As an example, consider an if statement with a single element: ABBREVIATED: if (something == true) ExecuteFunction(); PREFERRED: if (something == true) { ExecuteFunction(); } Indent nested statements and control structures Use a consistent treatment of indentation for nested statements and control structures. Elements that are contained within a higher level structure should be indented relative to that structure. Use tabs rather than white space. The sample function in the previous section illustrates indentation of control structures. CLEAR, CONSISTENT CODE: if (expression1) { if (expression2) { statement1; } else {

statement2; } } UNCLEAR, INCONSISTENT CODE: if (expression1) { if (expression2) { statement1; } else { statement2; } }

JavaScript includes
Any JavaScript to be used should be 'included' to allow easier code and document management: <script src="/js/main.js"></script> JavaScript should be at the bottom of the HTML page (before the ending </body> tag) to ensure fast page loading.

Comments
All functions should have concise comments describing the purpose of the function. For example: /* * Rollover function for turning an image 'on'. * Pass in a handle to the image object. * * All images must have a distinct name attribute * which is used as an index in the global image * array imgsOn. */ function imgOn(img) { if (document.images) { img.src = imgsOn[img.name].src; } }

Naming Conventions
It is very important to establish naming conventions in order to enhance code readability. With a few guidelines, it is possible to author code that is comprehensible to the developer world at large. Use descriptive names for variables and functions Create variable and function names that represent the data they store or the function they serve, respectively. For example, if you have a variable representing the number of goals England score in a game, call it numGoals, rather than ng. Use camel-case for names containing multiple words or segments For variable or function names that are composed of multiple words or segments, capitalize the letter just after the segment boundary. Examples: targetWindow, hotObject, numGoals.

JavaScript Validation
We will be validating the code using validators built-in to the code editors or online with JSLint (http://jslint.com/).

jQuery
Front-end developers will use the latest version of jQuery as the default library. The current version is jQuery v1.4.4 (as of 1/2011).

Cross-browser Testing
The list of browsers and operating systems for testing: Mozilla Firefox 3.6.x (Windows 7/Mac OS 10.6) Mozilla Firefox 4.x (Windows 7) Internet Explorer 7 (Windows XP) Internet Explorer 8 (Windows 7) Google Chrome 8.0.x (Windows 7) Safari 5.0.x (Mac OS 10.6)