HTML Standards & Guidelines s1

HTML5 AND CSS CODING CONVENTIONS (updated: 1/10/14)

INTRODUCTION:

This document describes the HTML5 and CSS3 coding style that you must use for this class. Most of these guidelines are widely accepted. However, alternative guidelines do exist in many areas. You must follow the guidelines in this document so that you will learn to code consistently and I will be able to grade consistently.

While reading the following sections, refer to the sample web page and its associated sample style sheet at the bottom of this document. Mimic the style used in those two pages. Before turning in a web page assignment, please review all the details of this document to make sure that you are using proper style. This will save you points and it will save me countless hours of grading. Please be kind. Thank you.

I have searched on the Internet for a satisfactory HTML coding-conventions document. Unfortunately, there is no universally agreed-upon document. In conducting my search, I've sifted through and evaluated many HTML coding practices. This document attempts to present the best HTML coding practices that conform to the HTML5 standard. Here are some of the sources I've used for this document:  W3C’s Doctypes and markup styles “Note for teachers” (http://www.w3.org/community/webed/wiki/Doctypes_and_markup_styles#A_note_for_teachers )  Google HTML/CSS Style Guide (http://google- styleguide.googlecode.com/svn/trunk/htmlcssguide.xml)  Preferred Syntax Style for HTML5 Markup (http://www.impressivewebs.com/html5-syntax- style/)

This document addresses only HTML coding style issues. It does not address user-interface design issues such as:  layout  color aesthetics  navigability  content  accessibility

FILES:

HTML file names should end in .html (not .htm).

Rationale: Using the full HTML acronym is more descriptive.

W3C's VALIDATION SERVICE: 2.

Validate every web page and every external style sheet by using W3C's validation services. The HTML and CSS validation services, respectively, are found here: http://validator.w3.org/ http://jigsaw.w3.org/css-validator/

Rationale: Cross-browser compatibility.

COMMENTS:

1. Short comments should be written on one line. Insert a space after the "". For example:

http://www.park.edu/compsci

2. Comments that require more than one line should use block-style indented text. For example:

GENERAL:

1. Include closing tags for all container-type elements. For example:

Park University, founded in 1625 by the Franciscan Monks, quickly gained national attention for its efforts in the fields of Alchemy and Computer Science.

This is not required by the HTML5 standard, but in the interest of consistency and readability, you should do it.

2. Use lowercase characters for all tags and attributes.

3. Enclose all attribute values in double quotes.

4. Because the name attribute can be used to identify elements in JavaScript, and JavaScript coding conventions suggests using camel case for multi-word variable names, use camel case for values for the name attribute. 3.

5. Do not use spaces around the equal sign when specifying an attribute value pair. For example:

Rationale: Group related entities together so that tag components are compartmentalized.

6. Blank lines:

 Insert blank lines to separate large logical chunks of code.

 Insert a blank line between the head and body sections.

 Do not insert a blank line unless there's a reason to do so.

7. Indentations:

 Indentations should use two spaces. Do not use tabs.

8. For void elements, HTML5 allows you to insert a blank space and slash ( /) at the left of the closing >, like this:

However, I require no blank space and no slash.

9. Avoid long lines:

 Within an IDE (like Visual Studio), it is annoying for programmers to have to scroll right in order to see the end of a line of code. Also, if you paste your code to a word processing document, it is annoying to see line wrap. To avoid these problems, split up long lines by pressing enter at natural breaking points. As a rule of thumb, try to avoid lines that require more than 80 characters (including blank spaces). Definitely avoid lines that require more than 100 characters (including blank spaces). For a definitive rule on line length, ask your teacher or manager.

TOP OF THE DOCUMENT:

1. Include the following line at the top of your HTML5 documents:

This will tell the browser to use the HTML5 version of HTML (because other versions of HTML use slightly different forms of the doctype tag).

Although most examples on the W3C and Google sites use all uppercase for the doctype tag (), the W3C and Google sites do not explicitly recommend uppercase. Since lowercase is legal for the doctype tag, and it’s the norm for all other tags, in the interest of consistency, you should use lowercase for doctype.

HEAD CONTAINER: 4.

The following items should be included in the order shown.

1. To avoid content being interpreted incorrectly, include the following charset meta element:

2. For grading purposes, I need to know your name, so you are required to include an author meta element. For example:

3. As an option, to help search engines find your pages, you may also want to include description and keywords meta elements. For example:

4. Include a meaningful title element on each page. For example:

Dean Family

Rationale: Helps search engine functionality.

5. For external style sheets, use the link element. For example:

BODY CONTAINER:

1. Block elements

 In presenting indentation rules, Google’s Style Guide refers to “block elements.” Unfortunately, Google doesn’t define what they mean by that term. Probably they are referring to the HTML 4 concept of block-level elements. After examining the W3C and WHATWG websites, I could not find a translation of “block-level element” to HTML5. However, in examining the W3C’s content model (http://www.w3.org/TR/2011/WD-html5-20110525/content-models.html) and its flow and phrasing categories, I think my definition below follows Google’s intent:

A block element is a flow element that is not also a phrasing element. Typically, browsers render block elements with 1 or 2 newlines above them and 1 or 2 newlines below them.

I plan to use the term “block element” throughout this document with the understanding that it is not a formal term endorsed by the W3C.

2. Blank lines

 Insert a blank line between large (≥ 5 lines?) block elements: 5.

 Do not insert blank lines between short, related heading elements. In the example below, h1 and h2 are short and related so there is no blank line separator. On the other hand, the heading elements should be separated from the p element with a blank line.

Doesn't every child dream of having his/her very own pet rat? With the "One Child, One Rat" program, that dream can become a reality.

3. Indentations:

 Most reputable HTML5 code (code that comes from reference textbooks and reference websites) uses indentations for (1) block elements whose code is too long for one line and for (2) continuation code for void elements whose code is too long for one line. For readability and consistency within our class, I require indentations for those two situations.

 Block elements:

○ In the following code, the text is indented inside the p block element because it’s too long to fit on one line. When the start and end tags appear on lines by themselves aligned in the same column, and the contained code is indented, that is called block notation.

Parkville's pristine white sandy beaches along the Missouri River attract vacationers from the world over. -Parkville Mayor, Jay Norman. After sun-worshipping all day, relax and enjoy Parkville's scintillating nightlife. Pirate Grounds is always a big hit with the singles!

○ Optionally, use block notation for short block elements that are inside other block elements. Thus, in the example below, it’s OK to indent the h1 block element inside of the header block element. The strong should not use block notation because it is not a block element.

Welcome to Parkville – Party Town, USA.

 Continuation code for void elements whose code is too long for one line:

○ If a tag cannot fit on one line, insert newlines at logical breaking points. The following examples illustrate what constitutes a logical breaking point. In the examples, the a tag cannot fit on one line so newline insertions are required. In the "bad" example, newlines are inserted after "href=" and "onmouseover=." Those are poor breaking points because the href and onmouseover assignments are broken up. In the "good" example, newlines are inserted after "web site –" and "return true;". Those are good breaking points because they help prevent the href, onmouseover, and onmouseout assignments from being broken up. 6.

bad: good:

For additional information on our ICS For additional information on our ICS program, program, check out this web site - onclick="return confirm('Are you sure?');"> http://www.park.edu/ics http://www.park.edu/ics

○ If a tag cannot fit on one line, the first continuation line should be indented. If more than one continuation line is required for a particular tag, the second, third, etc. continuation lines should be aligned with the first continuation line.

In the right-side example above, the a tag uses the recommended indentation.

4. Lists:

 Normally, you should nest ol, ul, dl, and li elements as follows:

 As shown above, when embedding a list inside of a list, the outer list's end tag must be placed below the embedded list.

5. Tables:

 Normally, you should nest table, thead, tbody, and tr elements as follows:

 As an alternative to the indentation shown above, if all the code in a tr container can fit on one line, then it’s acceptable to put the entire tr container code on one line.

6. Images and colors:

 Include width and height attributes for all img elements.

Rationale: Faster page loading.

 Include the alt attribute for all img elements. Use alt="" for decorative images.

Rationale: Alternate text serves as content when an image cannot be rendered or viewed normally.

 Do not use animated gifs or use them sparingly.

Rationale: Animations are annoying.

7. Character references:

 In the interest of readability, if there's a choice, use regular characters and not character references. Here's when it's appropriate to use a character reference:

○ Use a character reference to display a character that's not on the keyboard.

○ Use a character reference to display a character that would normally have a special meaning in HTML:

<, >, &

" and ', but only when they are inside of an attribute value string

○ Use an character reference if you need to:

Display a blank space without allowing a line break (to ensure that a group of words will be displayed on the same line).

Display multiple blank spaces without allowing whitespace collapsing.

 According to http://www.w3.org/TR/html4/charset.html, HTML character references fall into two categories – character entity references and numeric character references. Character entity references use the format – &name;. Numeric character references use the format – &#unicode- value;. Some symbols are represented by both a character entity reference and also a numeric 8.

character reference. For example, the less than symbol is represented by < and also by <. If a symbol is represented by both types of character references, you should use the character entity reference version because character entity references are more understandable. Some symbols are represented only by a numeric character reference and not a character entity reference. Because numeric character references are rather cryptic, you should provide a comment whenever you use a numeric character reference for the first time in a web page.

8. Miscellaneous:

 Plain text should not appear immediately within the html container, the head container, or the body container. Plain text should appear only within container elements that are within the body element. “Plain text” refers to characters that are not within a tag’s < and > symbols.

This is not required by the HTML5 standard, but it enables the page content to be described more fully, so it can be manipulated by CSS and JavaScript.

 Usually (but not always), a text element should be put inside a block element, but not directly inside the body container.

Rationale: Usually, text elements appear within the flow of surrounding text. If that’s the case, then, in applying the plain text rule above, the text element and its surrounding text should be put inside a block element.

 Do not specify precise sizes for text font. Instead, use header tags (h1, h2, etc.) or use style sheets with font-size values such as small, large, smaller, larger, 125%, etc.

Rationale: Using precise values is misleading since the size may still be different on different browsers.

KEEP CONTENT AND PRESENTATION SEPARATE:

1. Use HTML elements for content and CSS for presentation.

2. Since the b, i, and u elements implement presentational semantics, do not use them. Instead, use other elements that properly describe the text or use the following CSS property-value pairs:

font-weight: bold font-style: italic text-decoration: underline

STYLE SHEETS:

1. In an embedded style element and also in a link element to an external style sheet, include a type attribute with a value of "text/css". Here are two separate examples:

 CSS is the default type for a style element, so, functionally, there’s no difference between including and omitting type="text/css". To avoid clutter, omit it.

2. Comments:

 You should supply comments within your CSS code for any rules that are non-intuitive.  If the comment is short, insert it to the right of the rule that the comment applies to.  If the comment is long, insert it immediately above the rule(s) that the comment applies to. To give the comment more prominence, insert a blank line above the comment.  For grading purposes, I need to know your name, so for external style sheets, you are required to include your name in a comment at the top of the external style-sheet file. For example:

/* John Dean */

3. Surround logical groups of rules with blank lines.

4. Short rules:

 If you have just one property-value pair, or you have just a few property-value pairs, and none of the values are font-family lists, then you may put them on one line, with a space following each interior semicolon, like this:

.opening-statement {font-style: italic; color: blue;} .closing-statement {font-family: "Times New Roman", Times, serif;}

 With one-line rules, insert a blank space before the opening brace. There should be no blank spaces to the right of the opening brace and to the left of the closing brace.

5. Long rules:

 If you have a rule with a long heading and/or lots of property-value pairs, use block-style notation. For example:

body { background-color: white; color: black; a:visited: green; a:link: red; font-family: "Arial Black", Helvetica, sans-serif; }

 With block-style notation, place the opening brace on the same line as the selector, separated from the selector by one space.

6. Insert a blank space after a CSS property's colon. There should be no blank space before the colon.

7. For a font family list, insert a space after each comma.

8. Use hyphens to separate multi-word class values and multi-word id values.

9. Include a semicolon after the last property-value pair. 10.

 Although CSS standards allow you to omit the semicolon after the last property-value pair, you should include it. That way, if another rule is added later on, there will be less likelihood of accidentally forgetting the semicolon to separate the prior property-value pair from the new one.

10. Unless there’s a special reason, do not use the blink value for the text-decoration property. 11.

SAMPLE WEB PAGE

Dean Family

As usual, not much has happened to us this year. We just forge ahead with the usual mundane, ho-hum stuff. Let's see ... our dog Sophie is doing fine, Stacy's still working at Olathe Medical Center, we now have progeny, etc.

OK, I guess I'll start with the progeny. Her name is Jordan Alexandria Dean. Born one month early, March 5, medium height, medium build. She's doing great. As babies go, she's a keeper. Our parents tell us she's cute as a button. She smiles a lot, sits well, and has a very mature palette. Her hobbies include playing with Sophie, eating, burping, and curling up in front of a fire with a good book. A very likable kid.

Updated information:

Eventually, we'd like to add a family tree to this web page. If anyone in the family is interested in working on that project, please feel free to get started by evaluating these family tree tools:

Updated August 18, 2012

SAMPLE EXTERNAL STYLE SHEET (referenced as style.css in sample web page, above)

/* John Dean */ body {background-color: white; color: black;} nav {text-align: center;}

/* Apply special formatting to the links at the top. */ nav a, .current-tab { color: white; font-family: Arial, Helvetica, sans-serif; } nav a {background-color: #666666;} nav a:hover {background-color: blue;} .current-tab {background-color: green;} h1 {text-align: center;} hr { background-color: red; height: 1px; /* hr color works only if height is specified */ }

.date { color:red; font-family: "Trebuchet MS", Helvetica, sans-serif; font-size: smaller; }

HTML Standards & Guidelines s1

Our Furry Friend

The Common House Rat

Paradise in Parkville!

Dean Family

Dumb table
A	B
one	two
three	four