HTML Coding Convention

Improvements? Suggestions? email dna@hola.org

Coding conventions used by other companies: google | w3schools | @mdo

Consistent and Minimal

Most important rules:
Be consistent.
Be minimal.
Use tools.
Read these sections carefully.

Standard template

<!doctype html>
<html>
  <head>
    ...
  </head>
  <body>
    ..
  </body>
</html>

Indentation is 2 spaces (not 4 as in programming languages).
Column width is 79 chars, unless it breaks a single attribute value.

<li>Click the button and go to Hola's main website page link
<a href=http://hola.org>hola.org</a> and click about</li>

<li>Click the button and go to Hola's main website page link <a href=http://hola.org>hola.org</a> and click about</li>

<li>Click the button and go to Hola's main website page link <a
  href=http://hola.org>hola.org</a> and click about</li>

<li>Click the button and go to Hola's main website page link <a href=http://hola.org>
  hola.org</a> and click about</li>

<li>
  Click the button and go to Hola's main website page link
  <a href=http://hola.org>hola.org</a>
  and click about
</li>

<li>
  Click the button and go to Hola's main website page link
  <a href=http://hola.org>hola.org</a> and click about
</li>

<li>Click the button and go to Hola's main website page link
  <a href=http://hola.org>hola.org</a> and click about</li>

<p>
  Click the button and go to a website page link
  <a
    href=http://very.long/url/that/exeeds/79/charachters>Very very long page name</a>
  and click about
</p>

<p>
  Click the button and go to a website page link
  <a href=http://very.long/url/that/exeeds/79/charachters>
    Very very long page name</a> and click about
</p>

<p>
  Click the button and go to a website page link
  <a href=http://very.long/url/that/exeeds/79/charachters>Very very long page name</a>
  and click about
</p>

Items which contain less than two rows will end on the same line, while items which have more than two rows will end in a new line.

<li>Short line</li>

<li>This is a sentence that goes above 79 characters per line and therefore
  should be split into two rows</li>

<li>
  This is a sentence that goes above 79 characters and also above three
  lines and therefore it should be split into three rows and start/end the
  tags in new lines
</li>

<li>This is a bad example of sentance that goes above 79 characters and
  also above three lines but ends on the same last line as it not suppose
  to be</li>

Don't break the line before the closing tag of an empty element. If the line is too long, break it before an attribute.

<script src=http://somecdn.com/long-path/jquery.js>
</script>

<script src=http://somecdn.com/long-path/jquery.js></script>

<script
  src=http://somecdn.com/long-path/jquery.js></script>

<br> are like new line in text. Break the line after it.

Time flies when you are having fun!<br>You finished your first week.

Time flies when you are having fun!<br>
You finished your first week.

Time flies when you are having fun!<br><br><br>
You finished your first week.

Time flies when you are having fun!<br>
<br>
<br>
You finished your first week.

Element names and tags always in lower case.

<FORM ACTION=/submit>

<form action=/submit>

Hyperlinks

Always use absolute links and paths.

<a href=file>Click here</a>

<a href=dir/file>Click here</a>

<a href=../dir/file>Click here</a>

<a href=/root/path/file>Click here</a>

<a href=//site.com/path/file>Click here</a>

<a href=http://site.com/path/file>Click here</a>

Using relative links and paths are allowed only if they point to the same document.

<a href=#id>Click here</a>

<a href=file#id>Click here</a>

<a href=./file#id>Click here</a>

<a href=/path/to/file#id>Click here</a>

Special characters

Use & < > only in html, not inside tags.

<div>The answer is: a &gt; b</div>

<div title="The answer is: a &gt; b">Answer</div>

<div title="The answer is: a > b">Answer</div>

Avoid using &. Use plain & wherever possible.

Hello &amp; Goodbye!

Hello & Goodbye!

<a href=/get?type=user&amp;name=bat></a>

<a href=/get?type=user&name=bat></a>

Use & only where escaping needed - when followed by a-z0-9 and ;

<div>expression: x = a&b;</div>

<div>expression: x = a&amp;b;</div>

© ' ‘ ’ — • etc.:
use plain unicode UTF8 chars for it (validate your VI is :set encoding=utf-8).

<div>This &lsquo;download&rsquo; is the right one.</div>

<div>This ‘download’ is the right one.</div>

Quote only if needed

Due to minimalism
quote attribute values only if they need quoting (contain spaces, <>"'...). No need to quote &?=#.

<a href="http://site.com/download?option=1&set=1">Download</a>

<a href=http://site.com/download?option=1&set=1>Download</a>

<div id="download_btn">Download now</div>

<div id=download_btn>Download now</div>

<div class="download">Download now</div>

<div class=download>Download now</div>

<div class="download button">Download now</div>

Leave quotes on attributes that typically require quoting, such as JS fragments, and angular 'JS like' directives.

<div ng-click=img_click('brand')>

<div ng-click="img_click('brand')">

<div ng-if=!hide_filter>

<div ng-if="!hide_filter">

No need to quote empty attributes.

<option selected="">Customer</option>

<option selected>Customer</option>

Tag's id should be the first element

<h3 text="Bring value" id=bring_value>Bring value</h3>

<h3 id=bring_value text="Bring value">Bring value</h3>

Tag's class should be after id element

<h3 text="Bring value" class=bring_value>Bring value</h3>

<h3 class=more_value id=bring_value text="Bring value">Bring value</h3>

<h3 id=bring_value class=more_value text="Bring value">Bring value</h3>

<h3 class=more_value text="Bring value">Bring value</h3>

Avoid redundant type=text/javascript

Due to minimalism

<script type=text/javascript src=/jquery.js></script>

<script src=/jquery.js></script>

<link rel=stylesheet type=text/css href=/main.css>

<link rel=stylesheet href=/main.css>

Don't use <noscript> alt= title=

We are in the age of HTML5. We don't do web pages for browsers without JavaScript, or text based browsers. Therefore we avoid obsolete features such as <noscript> and alt=

<img src=/login.png alt="Click to login">

<img src=/login.png>

<script>... login form in JS...</script>
<noscript>...pure html login from without JS...<noscript>

<script>... login form in JS...</script>

Tooltips are great - they are the modern alternative to F1 help. But browsers tooltips (title=) don't display nice clear large fonts, cannot include HTML, just plain text.
Since tooltips are important, we avoid using the built-in browser tooltips, and we use our own jquery/angularjs tooltips, such as data-tooltip.

<div title="KB/s: kilobytes per second">4385</div>

<div data-tooltip title="<b>4385 KB/s</b>: kilobytes per second">4385</div>

SVG usage

SVGs should be placed in svg files, not embedded into the html.
Loading an SVG resource should be done with <use>.

<div>
  <svg>
    <path d="M 2,0 0,11 9,6 z"></path>
  </svg>
</div>

<div>
  <svg>
    <use xlink:href=/img/image.svg#cat></use>
  </svg>
</div>

And the svg file:

<svg version="1.1" xmlns="http://www.w3.org/2000/svg">
  <symbol id=cat viewBox="0 0 9 11">
    <path d="M 2,0 0,11 9,6 z"></path>
  </symbol>
</svg>

Include svg4everybody (polyfill for IE) library and call it after your html will be ready.

Multiple related SVGs may be put in the same svg file and loaded separately using <symbol> tag.

<div>
  <svg>
    <use xlink:href=/img/image.svg#dog></use>
    <use xlink:href=/img/image.svg#cat></use>
  </svg>
</div>

Apply styles (like fill) to each fragment of svg.

.my_svg use {
    fill: #ccc;
}

New window

Links should not open new windows/tabs - user can right-click himself to open new tab, or click BACK to return to current window

<a href=http://different.site.com target=_blank>click here</a>

<a href=http://different.site.com>click here</a>

Filenames

The path is part of the name. Don't include the path name in the filename.

pkg/svc/dashboard/pub/dashboard_table.html

pkg/svc/dashboard/pub/table.html

Main module page is called index.html.

pkg/svc/dashboard/pub/dashboard.html

pkg/svc/dashboard/pub/index.html

External JS/CSS

External JS/CSS code used on our site as-is should be via CDN, in the following order of preference:

AngularJS

Avoid data- prefix by default.

<div data-ng-if="is_customer">

<div ng-if="is_customer">

ExpressJS

TODO (missing description of our angular tree layout)