Coding Style Guide

Content Style Guide

HTML

I. Use correct document type. We use the following HTML5 standard for the redesign.

<!DOCTYPE html>

II. Use Lower Case Element Names

<p>This is a paragraph.</p>

</section>

III. Close All HTML Elements

<p>This is a paragraph.</p>

</section>

IV. Self-closing Elements

a. The forward slash should have one space preceding it.

<br />

V. Attributes

a. Attribute values should be lowercase

<a href="http://example.com" title="Description Here">Example</a>

VI. Quotes

a. All attributes must have a value, and must use double quotes (or single quotes).

VII. Image Attributes

a. Always use the alt attribute with images. It is important when the image cannot be viewed.

VIII. Loading Javascript in HTML

a. Use simple syntax for loading external scripts (the type attributes is not necessary).

b. Place Javascript at the bottom of the <body> unless there is a need to include it in the <head>.

IX. HTML File Naming Conventions

a. Avoid camel case, or underscore for html file names. Instead separate names by a hyphen. For example, avoid names like policeDepartment.html or police_department.html. Instead use police-department.html.

b. All file names must be lower case.

c. Use .html file extensions, instead of .htm.

X. URL Address

a. URL addresses (as seen on the address bar) must not end with index.html for consistency.

XI. Inline Styling

a. CSS should define all styling on a page. Avoid inline styling, like the following:

CSS

I. Structure

a. Each selector should be on its own line, ending in either a comma or an opening curly brace.

b. Property-value pairs should be on their own line, with one tab of indentation and an ending semicolon.

c. The closing brace should be flush left.

#selector-1,

#selector-2,

#selector-3 {

background: #fff;

color: #000;

}

II. Selectors

a. Try to follow BEM naming conventions as much as possible.

b. Use lowercase and separate words with hyphens when naming selectors.

c. Use human readable selectors that describe what element(s) they style.

d. Use double quotes around attribute values.

e. Avoid using html tag selector when you can use the id or class name. For example, instead of div.container, just use .container

#comment-form {

margin: 1em 0;

}

input[type="text"] {

line-height: 1.1;

}

III. Properties

a. Properties should be followed by a colon and a space.

b. All properties and values should be lowercase, except for font names, of course.

c. Use hex, instead of RGB, for colors.

#selector-1 {

background: #fff;

display: block;

margin: 0;

margin-left: 20px;

}

d. Order Properties Alphabetically

#overlay {

background: #fff;

color: #777;

padding: 10px;

position: absolute;

z-index: 1;

}

IV. Media Queries

a. Keep media queries grouped by media at the bottom of the stylesheet.

V. Commenting

XSLT

I. Template Names

a. Avoid camelcase and underscore. Instead use hyphen (dash) between words.

b. Use lowercase

c. Good examples include: page.xsl, footer.xsl, body-home.xsl, body-hub.xsl, ou-variable.xsl.

II. Avoid using xsl:for-each as much as possible, if we can template match.

III. Variable values are within the variable tag instead of using attributes. So, instead of:

<xsl:variable name="mystring" select="my text" />

We use:

<xsl:variable name="mystring">my text</variable>

IV. Use the {} shorthand for writing values inside of attributes. So instead of:

<h3>

<xsl:attribute name="class">

<xsl:value-of select="$product/@type" /></xsl:value-of>

</xsl:attribute>

<xsl:value-of select="$product/name" />

</h3>

We use:

<xsl:value-of select="$product/name" />

</h3>

V. Always use xsl:include in the master stylesheet to reference the templates defined in the external stylesheet – this has the same effect as just typing the templates within the master. Our redesign OU templates don’t use a lot of overrides (if at all), so we mostly use xsl:include.

VI. Function names that were created in-house are preceded with “tcc:”.

VII. Use xsl:import in the master stylesheet ONLY if you want to override a templates defined in the imported stylesheet. The example below overrides the <b><xsl:apply-templates/></b> with <i><xsl:apply-templates/></i>

code example

VIII. Use document() function to include an external XML or INC file. Before including these files, make sure they exist by using doc-available() function. For example:

<xsl:when test="$ou:parent-nav != ' '">

<xsl:value-of select="if (doc-available(concat($root, $top-level, '/_breadcrumb.xml')))

then document(concat($root, $top-level, '/_breadcrumb.xml'))/directory//title

else $top-level"/>

</xsl:when>

Updated January 02, 2024