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>

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 &amp; &lt; &gt; 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 &amp;. 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 &amp; only where escaping needed - when followed by a-z0-9 and ;

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

&copy; &apos; &lsquo; &rsquo; &mdash; &bull; 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>

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:

  1. couldflare cdnjs
  2. google
  3. microsoft
  4. jsdelivr

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)