Coding Best Practices

Overview

The cf_layout uses HTML 4.01 Transitional code for markup. Our goal is to use XHTML; we will convert the site into XHTML when the majority of the UMass Dartmouth site has been converted. The layout uses CSS for all visual display purposes. HTML should be used to mark up the structure of a web page, and CSS should be used to handle the appearance of text and images on the page.

To further these goals, we have listed below several coding practices and guidelines. Adhering to these will help bring your web site up to standards, make maintenance of the site easier, and provide a better user experience.

Note to OmniUpdate Users

By using OmniUpdate you do not have to edit the HTML code. We have taken care to have OmniUpdate use proper code wherever possible. However, many of the guidelines will apply to you, particularly those involving the use of one tag or attribute instead of another.

Coding Practices

• -If a tag has a closing tag, use it. HTML 4.01 has several tags (like '<p>') that have an end tag, but does not require their use. We do. This will help when we convert to XHTML (which always requires the closing tag) and ensure that CSS will be applied correctly. This does not apply to tags that do not have a close tag, like <img> and <br>.
  For example, this is incorrect:
  <p>Some paragraph text.
<p>Another paragraph.
This is correct:
  <p>Some paragraph text.</p>
<p>Another paragraph.</p>
• -Quote all attribute values. HTML does not require that you quote the value of HTML attributes. We do. This will help when we convert to XHTML (which requires all attributes be quoted). You may use single quotes (<a href='http://www.umassd.edu/'>UMass Dartmouth</a>) or double quotes (<a href="http://www.umassd.edu/">UMass Dartmouth</a>). The standard is to use double quotes. You may use whatever suits you, as long as you use it consistently.
• -All tags and attribute names must be lowercase.

Coding Guidelines

Do not use these tags:

-<i></i>. This tag produces italics text, and is better handled by CSS.
--If the purpose is to emphasize important text, use <em></em>.
--If the purpose is to make a text look italics, and has no special semantic meaning, use <span class="italics"></span>.

-<b></b>. This tag produces bold text, and is better be handled by CSS.
--If the purpose is to emphasize very important text, use <strong></strong>.
--If the purpose is to make a text look bold, and has no special semantic meaning, use <span class="bold"></span>

-<u></u>. This tag produces underlined text, and is better handled by CSS. In addition, using this visual format can be confusing for users, since an underline is commonly used to indicate a link that the user can click on.
--If you must make the text underlined, use <span class="underline"></span>.

-<center></center>. This tag centers text, and is better handled by CSS. Centered content should be used sparingly. It can be hard to read and is overused as a visual crutch.
-If you must center a content, use the "center" style. This style can be attached to any block element, for example, <p class="center">A sentence</p>.

-<font></font>. This tag controls the appearance of text, specifically it's size, color, and type face. It is better handled through CSS.

Do not use these attributes:

-align. This attribute applies to paragraphs, tables, and images. Use CSS instead.

-hspace, vspace. These attributes apply to images, and control the white space around the image. Use CSS instead.

-border. This attribute applies to tables and images. In tables it creates a line around each cell in the table; in images that are used as links, it controls the blue line around the image. Use CSS instead.

-color. This attribute applies to many tags. Use CSS instead.

-bgcolor. This attribute applies to table tags. Use CSS instead.

-valign. This attribute applies to table row and cell tags. Use CSS instead.

Proper Use of Tables

Use tables to present tabular data only. Do not use tables to control appearance, or to create multiple columns. Tables take extra time to download and display, and they present problems for people with disabilities. Unnecessary tables makes your site harder to use.

Multiple Columns

The layout has a limited ability to display content in multiple columns of text. The code to do so is:

<div class="twocolumnblock">
<div class="columnone">
<p>Content for the first column here.</p>
</div>
<div class="columntwo">
<p>Content for the second column here.</p>
</div>

The layout will not automatically resize the columns to match, nor automatically make the content in the columns of even length. You must control the amount of content yourself. The content within the columns must follow the same guidelines as on any other page.

You can also nest two column blocks, to create any number of columns. However, you must then work with the CSS to get the sizing of the columns correct so they will display correctly. This is a complicated process- do not attempt unless you have a firm grasp of CSS. For this reason, we recommend against using two columns unless absolutely necessary.

Proper use of <div> tags

<div> tags have no semantic meaning in themselves. They are used to identify sections of a document, and can act as hooks for CSS effects. The layout uses <div> tags to identify sections of the page (the header, the footer, the menu, etc.) and to help control the visual appearance of the web page.

There should be no reason to use a <div> tag on most pages. Subsections of a page can be indicated through content, header tags (<h1>, <h2>, etc.) and hard rules (<hr>). Do not use <div> tags where another tag would serve better. For example, do not use a <div> tag in place of a <p> tag, nor a <div> tag instead of a <h2> tag. Use the proper tag, and if necessary use CSS to change the visual effect of that tag.

Frames

Frames are not allowed using the layout.

Using Headers

Headers are the same as article headlines. They indicate a section of content or a subsection within a section. There are six levels of headers; if you need more, you should break up your page into several smaller pages.

Every page's content must begin with a headline encoded in a <h1> tag. The headline should indicate the purpose of the page. Some examples:

<h1>ENL 300 - British Literature.</h1> - for a page that details the British Literature course in a catalog.
<h1>Financial Aid Forms</h1> - for a page that makes forms availiable for download and/or links to more information about those forms.
<h1>Student Organizations Alphabetical Listing</h1> - for a page with an alphabetical listing of student organizations.

The <h1> headline can be styled using CSS to appear as desired. Rarely, you may need to hide the <h1> headline. If so, give it a class of "hidden". This will remove it from view.

Beneath the <h1> can appear any content. If subheadings are necessary, start with <h2> and work downwards to <h6>. Most pages should only require down to <h4>. For example:

<h1>Page headline.</h1>

<p>Some optional explanatory text.</p>

<h2>Subheading one.</h2>

<p>Text under subheading.</p>

<h3>Sub subheading one</h3>

<p>Text under sub subheading one.</p>

<h2>Subheading two.</h2>

Semantic vs. Visual Markup

Many of these rules and guidelines will seem confusing or unnecessary to those who do not understand the difference between semantic and visual markup. It has to do with a difference is writing emphasis, and understanding what a block of text is doing. Understanding the difference can help you produce better websites that are friendlier to users, and will help you understand the reasoning behind the rules and guidelines.

Visual markup means using tags and attributes to convey a visual appearance. Some tags are used exclusively for this, including <font>, <b> and <i>. Others have another purpose, such as <blockquote>, <table> and <h4>, but have a visual affect that is similar to the effect writers want. Visual markup causes several problems:

• Maintenance of the page becomes very difficult and can produce unexpected results. Many users of OmniUpdate and Dreamweaver have experienced problems where a change in color to one paragraph seems to change the color in every paragraph, or has a completely different effect elsewhere in the page. One reason this happens is because the visual effects are tied to tags that are nested within each other, each nested tag overriding the effect of another. When the color is changed, the tag that set that color is changed, and the other tag it was overriding comes into play. It also happens when content is removed but the formatting tag isn't; the tag sits there unknown until someone tries to make a change and accidentally uses that forgotten formatting tag. It results in wasted time and frustration on the editor.
• The page content looses its meaning. Many users with disabilities rely on HTML tags to help them understand the context and meaning of the text. Thier computers will read the <h4> text as a headline, and a <blockquote> text as a blockquote. These users become disoriented and confused when the wrong tag is used. It may work fine for the people who can see the web page and infer context from that, but that is only one part of the total web population. When this is combined with <font> tags to change the appearance, it gets even worse. Users with disabilities have to work extra hard to understand what the page is about, when they shouldn't have to.
• It creates more work when writing content. In addition to writing instructions, descriptions, and other page content, and making sure that is done well, visual markup forces the writer to deal with design issues. It makes the writer do extra work to make sure all the section headings look the same, all of the colors are consistent, and more. Most writers have little time as it is to write page content, let alone make sure it looks nice and consistent. When this time isn't taken, the result is a site that looks unprofessional and sloppy, despite the work put into it.

Semantic markup, on the other hand means using tags and attributes to convey meaning. A <h1> is not used to create a block of large text, but instead to convey the main purpose of the page in a header. A <blockquote> is not used to indent a block of text, but to indicate the text it surrounds is a quote cited from an outside source. The visual effect of a tag is not important; its purpose is. Semantic markup solves several problems:

• Maintenance of the page becomes much easier. Since little to no visual formatting tags are in the page, there are fewer if any surprises when the text is changed.
• The page content gains meaning. Users with disabilities will understand the text the same as users who can see the page. Changes to the CSS, with the resulting visual changes, will not affect the page's meaning or usefulness. This extra meaning happens without any extra effort on the part of the writer.
• Less work is needed to write and maintain content. The writer only has to worry about the content of a page, and putting it into the appropriate headings and blocks. Since the visual formatting is of no concern, less effort is needed to write and check the document. As long as the writer follows the guidelines and rules, he doesn't have to worry about how it will look. It will be taken care of for him.

The guidelines and rules for writing web pages will help you write semantic markup with all of its advantages.