Javascript Coding Guidelines

Created by: Will, Last modification: 13 Jul 2008 (13:34 UTC) by WaterDragon
These guidelines are specific to contributing Javascript to bitweaver. At the time of the creation of these guidelines javascript in bitweaver was getting a little out of hand. If you look at files in bitweaver and find they do not conform to these guidelines, please do not imitate past poor practices, these are old lines of code that simply still need to be rewritten. Please contribute all new javascript by conforming to the following:

Start With bitweaver's Basic Coding Conventions

In addition to the guidelines laid out here, please follow our general Coding Guidelines, where applicable.

Where To Put Javascript

Location:
Javascript is best placed in one of two locations. Either in a .js file or in a package's header_inc.tpl file. ALL package .js files should go in a scripts/ directory in their package. It is not always advantageous however to put javascript in .js files. Use of js files causes the browser to make more http requests. If there are a lot of js files required then this can slow page load time. For small amounts of javascript its better to put it into the header_inc.tpl file where it will be rendered inline in the HEAD tag. It is ok to also put the js in a separate template and include that in the header_inc.tpl file.

Some bitweaver wide .js files will live in util/ but that will be rare, most .js files should be in their package.

AVOID INLINE JS AS MUCH AS POSSIBLE INSIDE THE BODY TAGS. Sometimes this is hard to do, but in most cases you can. It is poor practice to litter HTML with SCRIPT tags. Sometime people do this to cause something to be rendered on load. If you want a function called onload you should instead you should assign the function to the body onload event. You can do this in your php by assigning your javascript function like this:


<?php
$gBitSystem
->mOnload[] = 'BitPackage.someFunction();';
?>


File Naming:
.js files should use camel case in the names like LibertyComments.js

.tpl based javascript files, such as json tpls, should the following this name construction: file_name.js.tpl and will of course live in the relative package's templates/ dir

We think it is ok however to add javascript onclick onmouseup onmousedown etc events to your html DOM elements. So long as the events call predefined functions. DO NOT construct functions in your DOM event handlers. Some practitioners favor binding events to DOM elements in javascript, but we think it is easier to maintain their function calls by including them in the html.

When using javascript in anchor tags put the javascript in on the onclick or other javascript event handlers (onmouseup onmousedown etc). DO NOT PUT JAVASCRIPT in HREF. Alternative non-javascript paths should go in the href property, or if you have no non-javascript path, construct your a tag link with a javascript:void(0); like so:


<?php
<a href="javascript:void(0);" onclick="BitBase.doSomething()">Do Something</a>
?>


Name Spaces

Name Space Objects
All new javascript functions and variables should be attached to a name space like object. variables and functions SHOULD NOT be written to the global javascript space. Here is an examples, including case requirements:


<?php
BitPackage 
= {
   
"PKG_CONSTANT":"foo",

   
"pkg_var":0,

   
"someOtherVar":"bar";

   
"pkgFunction": function(){
      
//do something
   
}
}
?>


This could also be written like this, its the same thing:


<?php
BitPackage 
= {}
BitPackage.PKG_CONTANT "foo";
BitPackage.pkg_var 0;
BitPackage.someOtherVar:"bar";
BitPackage.pkgFunction = function(){};
?>


No more of this:

someFunction(){}

or this:

some_function(){}

or this:

some_var = "foo";

or this:

someVar = "foo";

Without a name space the above becomes globals. This can lead to unintended variable and function overwriting - which gets ugly.

Creating Prototypes:
If you want to create a prototype it is better to attach it to the name space rather than put it in the global space; by nesting things in the name space others can still use the base name space without disrupting the prototype. Here is an example, with a check on the name space to make sure it exists already - you should use this too - it allows people to add to the name space in other places with out all of us killing each other's work:


<?php
if (typeof(BitPackage) == 'undefined') {
   
BitPackage = {};
}
BitPackage.MyProto = function(){
   
"some_var":"foo",
}
BitPackage.MyProto.prototype = {
   
"alertSomeVar": function(){
        
alert(this.some_var);
   }
}
?>


Note: we capitalize the prototype function name to distinguish it from a regular function.

Comments

JS Library discussion

by Lester Caine, 29 Apr 2010 (06:50 UTC)
I have not found a page for JS library discussion, so I'm hanging that here for the moment ...
Useful JS library comparison 'wiki.freaks-unidos.net/javascript-libraries'