Note
In addition to the :doc:`general` guidelines, the following sections describe JavaScript specific rules. Code Conventions for the JavaScript Programming Language should be your Bible.
Important
- Use dot annotation
test.base.js
for JavaScript file naming. - Use a library's prefix, such as
cl.xplorer.js
orjquery.tablesorter.js
, for file naming. - Name
variablesLikeThis
,ClassesLikeThis
,CONSTANTS_LIKE_THIS
andevents-like-this
. - Use the
js-
prefix when working with JS-related selectors and do not add styling to it. - Never use comma separation for variable declarations like
var a, b, c;
. - Never use $ for variable names such as
var $el = $('.el');
. - We are using the
Cl.
singleton for all custom JavaScript code.
When using jQuery to refer to a DOM instance, always use the js-
prefix to separate styles from JavaScript functionality. For example:
<div class="addon addon-gallery js-addon-gallery"></div>
.
In this example, addon and addon-gallery have styles attached to them, js-plugin-gallery refers to the JavaScript functionality attached to the DOM element.
Even when removing the JS class (or just waiting for JavaScript to kick in), the addon should still look good.
// bad
CL.Utils.js, jquery_tooltip.js, testWebsiteCreateNew.js
var $jquery, current_state;
var test-website-create-new;
// good
cl.utils.js, jquery.tooltip.js or test.website.create.new.js
var jquery;
var currentState;
var nextIndexValue;
Important
- Always declare variables on top of the functions and not in between.
- Always use semicolons
and full brackets, except in shorthand like
var i = (true) ? 'yes' : 'no';
. - Use proper spaces for
if (true) {} else {}
orfunction () {}
.
// bad
function(cont){
var c = $(cont);
if(c.length) {
// do something
}
else
{
// so something else
}
}
// good
function (container) {
var container = $(container);
if (container.length) {
// do something
} else {
// so something else
}
}
Important
- Keep
<script>
and the following starting closure on the same level. - Separate all script tags using
{% addtoblock "js" %}{% endaddtoblock %}
. - Never use JavaScript attributes on HTML elements such as
onclick=""
oronload=""
. - Don't add inline JavaScript within HTML, implement JavaScript through files only. Instantiate functionality from within the JavaScript file instead.
// bad
<div class="dashboard" id="dashboard"> ... </div>
{% addtoblock "js" %}
<script src="{% static "js/addons/cl.dashboard.js" %}"></script>
{% endaddtoblock %}
<!-- javascript gets initialised inside the template -->
{% addtoblock "js" %}
<script>
jQuery(document).ready(function () {
Cl.dashboard.init('#dashboard');
});
</script>
{% endaddtoblock "js" %}
// good
<div class="dashboard js-dashboard" data-dashboard="..."> ... </div>
<!-- javascript gets initialised within the file -->
{% addtoblock "js" %}<script src="{% static "js/addons/cl.dashboard.js" %}"></script>{% endaddtoblock %}
Important
- Use the singleton pattern to avoid globals.
- Use the module pattern to structure code.
- Avoid the functional pattern