babsgosgens · August 29, 2015 13:56
diff --git a/Jooml Markup Styleguide b/Jooml Markup Styleguide
 // This document is a compilated resource from various documents on good practices found elsewhere (see a list of resources at the end of this document).
 // We hesitate to use the words 'good' or 'bad', since this is a contributor's guide for our code base and not a critique of techniques. We've replaced them with:
 // No (as in, not our way) and Yes (this is what we expect from contributions)

 // Elements can be referred to as Tags or Elements, or both


 /* General principles */

 // All code in any code-base should look like a single person typed it, no matter how many people contributed.
 // Strictly enforce the agreed upon style.
 // Use British English spelling for comments and class names


 /* Doctype */

 // Always use the minimal, versionless doctype.

 <!doctype html>


 /* Language */

 // Always define which language the page is written in.

 <html lang="en">


 /* Encoding */

 // Always define the character encoding. The encoding should be defined as early as possible.
 // Use UTF-8 (no BOM).
 // Make sure your editor uses UTF-8 as character encoding, without a byte order mark.
 // Specify the encoding in HTML templates and documents via <meta charset="utf-8">. Do not specify the encoding of style sheets as these assume UTF-8.

 <meta charset="utf-8">

 (More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS(http://www.w3.org/International/tutorials/tutorial-char-enc/).)


 /* Protocol */

 // Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless the respective files are not available over both protocols.
 // Omitting the protocol—which makes the URL relative—prevents mixed content issues and results in minor file size savings.
 // @todo: examples of using J! Framework to render urls to local resources (JUri::root(), $this->baseurl)

 // Yes
 <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
 <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

 // No
 <script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>

 // Yes
 .example {
  background: url(//www.google.com/images/example);
 }

 // No
 .example {
  background: url(http://www.google.com/images/example);
 }


 /* Elements and Attributes */

 // Always include html, head, and body tags.


 /* Capitalization */

 // All code has to be lowercase: This applies to HTML element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings).

 // Yes
 <a href="index.php">Home</a>

 // No
 <A HREF="/">Home</A>

 // Yes
 a {
    color: #a3a3a3;
 }

 // No
 a {
    color: #A3A3A3;
 }


 /* Class Names */

 // Use clear, thoughtful, and appropriate names for HTML classes. The names should be informative both within HTML and CSS files.
 Avoid systematic use of abbreviated class names. Don't make things difficult to understand.
 // Naming is hard, but very important. It's a crucial part of the process of developing a maintainable code base, and ensuring that you have a relatively scalable interface between your HTML and CSS/JS.
 // Class names should use hyphens for readability. CamelCase is in conflict with our capitalization rule.

 // @todo guides for css naming conventions - is as important as formatting rules!


 // Yes
 <div class="content-wrap"></div>

 // No
 <div class="contentWrap"></div>

 // Yes
 <div class="column-body is-scrollable"></div>

 .is-scrollable {
    overflow: auto;
 }

 .column-body {
    background: #000;
 }

 // No
 <div class="cb s-scr"></div>

 .s-scr {
    overflow: auto;
 }

 .cb {
    background: #000;
 }






 /* Trailing Whitespace */
 // Remove trailing white spaces. Trailing white spaces are unnecessary and can complicate diffs.

 // Yes
 <p>Yes please.</p>

 // No
 <p>No, thank you. </p>


 /* Script, Link and Style  Tags */

 // No type or language attributes on script tags.
 // No type attribute on link or style tags.
 // Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
 // Specifying type attributes in these contexts is not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers.

 // Yes
 <script src="..."></script>
 <script></script>
 <link rel="stylesheet" href="...">
 <style></style>

 // No
 <script src="..." type="text/javascript"></script>
 <link rel="stylesheet" href="..." type="text/css">



 /* Attribute and Attribute Quotes */

 // Attribute values should be quoted using double ("") quotes.
 // Optional attributes should be omitted.

 // Yes
 <script src="..."></script>

 // No
 <script src='...'></script>


 /* Boolean Attributes */

 // Use attribute/value pairs for boolean attributes

 // Yes
 <input type="checkbox" value="on" checked="checked">

 // No
 <input type="checkbox" value="on" checked>

 // Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs:

 <a class="..."
 data-action="..."
 data-id="..."
 href="...">
    <span>Text</span>
 </a>


 /* Attribute Order */

 // HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.

 * class
 * id
 * data-*
 * Everything else

 // Yes
 <a class="..." id="..." data-name="..." href="...">Text</a>

 // No
 <a href="..." class="..." id="..." data-name="...">Text</a>


 /* Closing Tags */

 // Optional closing tags should be included.

 // Yes
 <p></p>

 // No
 <p>

 /* Self Closing Tags */

 Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.

 // Yes
 <br>

 // No
 <br />


 /* Semantics */

 // Use HTML according to its purpose, e.g. use elements for what they have been created for. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.

 // yes
 <a href="recommendations/">All recommendations</a>

 // No
 <div onclick="goToRecommendations();">All recommendations</div>


 # HTML Formatting Rules


 /* General Formatting */

 // Use a new line for every block, list, or table element, and indent every such child element.
 // Independent of the styling of an element (as CSS allows elements to assume a different role per display property), put every block, list, or table element on a new line.
 // Also, indent them if they are child elements of a block, list, or table element.

 // Yes
 <div class="tweet">
    <a href="...">
        <span class="extra-wrap">
            <img src="..." alt="">
        </span>
    </a>
    <button>
        <span class="some-wrap">Click me</span>
    </button>
 </div>

 // No
 <div class="tweet">
    <a href="..."><span class="extra-wrap"><img src="..." alt=""></span></a>
    <button><span class="some-wrap">Click me</span></button>
 </div>



 // Use whitespace to visually separate groups of related markup and to improve the readability and maintainability of your HTML. Use two empty lines between larger blocks, and use a single empty line between child blocks of larger blocks. Be consistent. (If you are worried about your document's size, spaces (as well as repeated use of the same strings - for instance class names) are excellent candidates for compression. Also, you may use a markup minifier to decrease your document's file size.)

 // (If you run into issues around whitespace between list items it’s acceptable to put all li elements in one line. A linter is encouraged to throw a warning instead of an error.)
 // (Keep line-length to a sensible maximum, e.g., 80 columns.)

 // Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.

 <blockquote>
    <p><em>Space</em>, the final frontier.</p>
 </blockquote>


 <ul>
    <li>Moe</li>
    <li>Larry</li>
    <li>Curly</li>
 </ul>


 <table>
    <thead>
        <tr>
            <th scope="col">Income</th>
            <th scope="col">Taxes</th>
        </tr>
    <tbody>
    <tr>
        <td>$ 5.00</td>
        <td>$ 4.50</td>
    </tr>
 </table>


 /* Indentation */

 // Don't indent inside html, body, script, or style. Indent inside head and all other elements.
 // Indent by four spaces at a time. Don’t use tabs or mix tabs and spaces for indentation.

 // Yes

 <!doctype html>
 <html lang="en">
 <head>
    <meta charset="utf-8">
    <title>Sample Page</title>
 
    <link rel="stylesheet" href="/style.css">
    <style>
    body {
        font-size: 100em;
    }
    </style>
 
    <script src="/jquery.js"></script>
    <script>
    $(function() {
        $( "p" ).text( $.fn.jquery );
    });
    </script>
 </head>
 <body>
 
 <p>Joomla! is awesome!<p>
 
 </body>
 </html>




 /* Comments */

 // @todo: comment styles in JS, CSS, HTML
 // Explain code as needed, where possible.
 // Use comments to explain code: What does it cover, what purpose does it serve, why is respective solution used or preferred? (This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)

 // For more complex blocks of HTML, it may be useful to add a comment to the closing tag:

 <div class="parent">

    <div class="child">
    </div><!-- /child -->

 </div><!-- /parent -->



 /* Use valid HTML where possible. */

 //  Use tools such as the W3C HTML validator to test. Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper HTML usage.

 // @todo: list various testing tools:
 * http://validator.w3.org/nu/
 * http://csslint.net/




 /* Multimedia Fallback */

 // For multimedia, such as images, videos, animated objects via canvas, make sure to offer alternative access. For images that means use of meaningful alternative text (alt) and for video and audio transcripts and captions, if available.
 // Providing alternative contents is important for accessibility reasons: A blind user has few cues to tell what an image is about without @alt, and other users may have no way of understanding what video or audio contents are about either. (For images whose alt attributes would introduce redundancy, and for images whose purpose is purely decorative which you cannot immediately use CSS for, use no alternative text, as in alt="".)

 // Yes
 <img src="spreadsheet.png" alt="Spreadsheet with statistic data.">
 <img src="logo.png" alt="">

 // No
 <img src="spreadsheet.png">


 /* Entity References */

 // Do not use entity references. There is no need to use entity references like &mdash;, &rdquo;, or &#x263a;, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
 // The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).

 // Yes
 The currency symbol for the Euro is “€”.

 // No
 The currency symbol for the Euro is &ldquo;&eur;&rdquo;.


 /* Separation of Concerns */

 // Strictly keep structure (markup), presentation (styling), and behavior (scripting) apart, and try to keep the interaction between the three to an absolute minimum.
 // That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.
 // Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.
 // @todo add guidelines on how to deal with SOC in a Joomla! context


 /* Component Output */

 // @todo guidelines for component output

 /* Structural elements */

 // Structural elements must have a title. This will be helpful to users accessing your content with screen readers. If a structural element cannot be given a meaningful title, it is likely that a non-structural element (div) should have been used instead.




 # Markup


 /* Image Tags */

 // Image elements (<img>) MUST have an alt attribute. Image elements MAY have a height and width attributes.


 /* Inline CSS */

 // Inline CSS MUST be avoided. When altering states using JavaScript, use CSS to define your states, and only use onobtrusive JavaScript to alter class names whenever possible.

 /* Style Attributes */
 You should NOT USE border, align, valign, or clear attributes. Avoid use of style attributes, except where using syndicated content or internal syndicating systems.

 /* Alt and title attributes */


 // @todo http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml



 /* Consulted Resources */
 http://contribute.jquery.org/style-guide/html/
 http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml
 http://csswizardry.com/2012/04/my-html-css-coding-style/
 https://github.com/necolas/idiomatic-html
 http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml
	// This document is a compilated resource from various documents on good practices found elsewhere (see a list of resources at the end of this document).
	// We hesitate to use the words 'good' or 'bad', since this is a contributor's guide for our code base and not a critique of techniques. We've replaced them with:
	// No (as in, not our way) and Yes (this is what we expect from contributions)

	// Elements can be referred to as Tags or Elements, or both


	/* General principles */

	// All code in any code-base should look like a single person typed it, no matter how many people contributed.
	// Strictly enforce the agreed upon style.
	// Use British English spelling for comments and class names


	/* Doctype */

	// Always use the minimal, versionless doctype.

	<!doctype html>


	/* Language */

	// Always define which language the page is written in.

	<html lang="en">


	/* Encoding */

	// Always define the character encoding. The encoding should be defined as early as possible.
	// Use UTF-8 (no BOM).
	// Make sure your editor uses UTF-8 as character encoding, without a byte order mark.
	// Specify the encoding in HTML templates and documents via <meta charset="utf-8">. Do not specify the encoding of style sheets as these assume UTF-8.

	<meta charset="utf-8">

	(More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS(http://www.w3.org/International/tutorials/tutorial-char-enc/).)


	/* Protocol */

	// Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless the respective files are not available over both protocols.
	// Omitting the protocol—which makes the URL relative—prevents mixed content issues and results in minor file size savings.
	// @todo: examples of using J! Framework to render urls to local resources (JUri::root(), $this->baseurl)

	// Yes
	<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
	<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

	// No
	<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>

	// Yes
	.example {
	background: url(//www.google.com/images/example);
	}

	// No
	.example {
	background: url(http://www.google.com/images/example);
	}


	/* Elements and Attributes */

	// Always include html, head, and body tags.


	/* Capitalization */

	// All code has to be lowercase: This applies to HTML element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings).

	// Yes
	<a href="index.php">Home</a>

	// No
	<A HREF="/">Home</A>

	// Yes
	a {
	color: #a3a3a3;
	}

	// No
	a {
	color: #A3A3A3;
	}


	/* Class Names */

	// Use clear, thoughtful, and appropriate names for HTML classes. The names should be informative both within HTML and CSS files.
	Avoid systematic use of abbreviated class names. Don't make things difficult to understand.
	// Naming is hard, but very important. It's a crucial part of the process of developing a maintainable code base, and ensuring that you have a relatively scalable interface between your HTML and CSS/JS.
	// Class names should use hyphens for readability. CamelCase is in conflict with our capitalization rule.

	// @todo guides for css naming conventions - is as important as formatting rules!


	// Yes
	<div class="content-wrap"></div>

	// No
	<div class="contentWrap"></div>

	// Yes
	<div class="column-body is-scrollable"></div>

	.is-scrollable {
	overflow: auto;
	}

	.column-body {
	background: #000;
	}

	// No
	<div class="cb s-scr"></div>

	.s-scr {
	overflow: auto;
	}

	.cb {
	background: #000;
	}






	/* Trailing Whitespace */
	// Remove trailing white spaces. Trailing white spaces are unnecessary and can complicate diffs.

	// Yes
	<p>Yes please.</p>

	// No
	<p>No, thank you. </p>


	/* Script, Link and Style Tags */

	// No type or language attributes on script tags.
	// No type attribute on link or style tags.
	// Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
	// Specifying type attributes in these contexts is not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers.

	// Yes
	<script src="..."></script>
	<script></script>
	<link rel="stylesheet" href="...">
	<style></style>

	// No
	<script src="..." type="text/javascript"></script>
	<link rel="stylesheet" href="..." type="text/css">



	/* Attribute and Attribute Quotes */

	// Attribute values should be quoted using double ("") quotes.
	// Optional attributes should be omitted.

	// Yes
	<script src="..."></script>

	// No
	<script src='...'></script>


	/* Boolean Attributes */

	// Use attribute/value pairs for boolean attributes

	// Yes
	<input type="checkbox" value="on" checked="checked">

	// No
	<input type="checkbox" value="on" checked>

	// Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs:

	<a class="..."
	data-action="..."
	data-id="..."
	href="...">
	<span>Text</span>
	</a>


	/* Attribute Order */

	// HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.

	* class
	* id
	* data-*
	* Everything else

	// Yes
	<a class="..." id="..." data-name="..." href="...">Text</a>

	// No
	<a href="..." class="..." id="..." data-name="...">Text</a>


	/* Closing Tags */

	// Optional closing tags should be included.

	// Yes
	<p></p>

	// No
	<p>

	/* Self Closing Tags */

	Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.

	// Yes
	<br>

	// No
	<br />


	/* Semantics */

	// Use HTML according to its purpose, e.g. use elements for what they have been created for. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.

	// yes
	<a href="recommendations/">All recommendations</a>

	// No
	<div onclick="goToRecommendations();">All recommendations</div>


	# HTML Formatting Rules


	/* General Formatting */

	// Use a new line for every block, list, or table element, and indent every such child element.
	// Independent of the styling of an element (as CSS allows elements to assume a different role per display property), put every block, list, or table element on a new line.
	// Also, indent them if they are child elements of a block, list, or table element.

	// Yes
	<div class="tweet">
	<a href="...">
	<span class="extra-wrap">
	<img src="..." alt="">
	</span>
	</a>
	<button>
	<span class="some-wrap">Click me</span>
	</button>
	</div>

	// No
	<div class="tweet">
	<a href="..."><span class="extra-wrap"><img src="..." alt=""></span></a>
	<button><span class="some-wrap">Click me</span></button>
	</div>



	// Use whitespace to visually separate groups of related markup and to improve the readability and maintainability of your HTML. Use two empty lines between larger blocks, and use a single empty line between child blocks of larger blocks. Be consistent. (If you are worried about your document's size, spaces (as well as repeated use of the same strings - for instance class names) are excellent candidates for compression. Also, you may use a markup minifier to decrease your document's file size.)

	// (If you run into issues around whitespace between list items it’s acceptable to put all li elements in one line. A linter is encouraged to throw a warning instead of an error.)
	// (Keep line-length to a sensible maximum, e.g., 80 columns.)

	// Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.

	<blockquote>
	<p><em>Space</em>, the final frontier.</p>
	</blockquote>


	<ul>
	<li>Moe</li>
	<li>Larry</li>
	<li>Curly</li>
	</ul>


	<table>
	<thead>
	<tr>
	<th scope="col">Income</th>
	<th scope="col">Taxes</th>
	</tr>
	<tbody>
	<tr>
	<td>$ 5.00</td>
	<td>$ 4.50</td>
	</tr>
	</table>


	/* Indentation */

	// Don't indent inside html, body, script, or style. Indent inside head and all other elements.
	// Indent by four spaces at a time. Don’t use tabs or mix tabs and spaces for indentation.

	// Yes

	<!doctype html>
	<html lang="en">
	<head>
	<meta charset="utf-8">
	<title>Sample Page</title>

	<link rel="stylesheet" href="/style.css">
	<style>
	body {
	font-size: 100em;
	}
	</style>

	<script src="/jquery.js"></script>
	<script>
	$(function() {
	$( "p" ).text( $.fn.jquery );
	});
	</script>
	</head>
	<body>

	<p>Joomla! is awesome!<p>

	</body>
	</html>




	/* Comments */

	// @todo: comment styles in JS, CSS, HTML
	// Explain code as needed, where possible.
	// Use comments to explain code: What does it cover, what purpose does it serve, why is respective solution used or preferred? (This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)

	// For more complex blocks of HTML, it may be useful to add a comment to the closing tag:

	<div class="parent">

	<div class="child">
	</div><!-- /child -->

	</div><!-- /parent -->



	/* Use valid HTML where possible. */

	// Use tools such as the W3C HTML validator to test. Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper HTML usage.

	// @todo: list various testing tools:
	* http://validator.w3.org/nu/
	* http://csslint.net/




	/* Multimedia Fallback */

	// For multimedia, such as images, videos, animated objects via canvas, make sure to offer alternative access. For images that means use of meaningful alternative text (alt) and for video and audio transcripts and captions, if available.
	// Providing alternative contents is important for accessibility reasons: A blind user has few cues to tell what an image is about without @alt, and other users may have no way of understanding what video or audio contents are about either. (For images whose alt attributes would introduce redundancy, and for images whose purpose is purely decorative which you cannot immediately use CSS for, use no alternative text, as in alt="".)

	// Yes
	<img src="spreadsheet.png" alt="Spreadsheet with statistic data.">
	<img src="logo.png" alt="">

	// No
	<img src="spreadsheet.png">


	/* Entity References */

	// Do not use entity references. There is no need to use entity references like —, ”, or ☺, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
	// The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).

	// Yes
	The currency symbol for the Euro is “€”.

	// No
	The currency symbol for the Euro is “&eur;”.


	/* Separation of Concerns */

	// Strictly keep structure (markup), presentation (styling), and behavior (scripting) apart, and try to keep the interaction between the three to an absolute minimum.
	// That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.
	// Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.
	// @todo add guidelines on how to deal with SOC in a Joomla! context


	/* Component Output */

	// @todo guidelines for component output

	/* Structural elements */

	// Structural elements must have a title. This will be helpful to users accessing your content with screen readers. If a structural element cannot be given a meaningful title, it is likely that a non-structural element (div) should have been used instead.




	# Markup


	/* Image Tags */

	// Image elements (<img>) MUST have an alt attribute. Image elements MAY have a height and width attributes.


	/* Inline CSS */

	// Inline CSS MUST be avoided. When altering states using JavaScript, use CSS to define your states, and only use onobtrusive JavaScript to alter class names whenever possible.

	/* Style Attributes */
	You should NOT USE border, align, valign, or clear attributes. Avoid use of style attributes, except where using syndicated content or internal syndicating systems.

	/* Alt and title attributes */


	// @todo http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml



	/* Consulted Resources */
	http://contribute.jquery.org/style-guide/html/
	http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml
	http://csswizardry.com/2012/04/my-html-css-coding-style/
	https://github.com/necolas/idiomatic-html
	http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml