Commons:Javascript styleguide

From Wikimedia Commons, the free media repository

To keep the growing Javascript code base on Commons readable, compact, well documented, free of redundancies, and as cross-browser compatible as possible a few rules have to be enforced.

[edit] Use single whitespace indent

More than one space indent gets annoying when editing the code in a browser window. Tab input is not possible in many browsers and keeping up with the indentation count when using multiple spaces can quickly get difficult. Reducing the indent does not noticably impact readability, but can considerably reduce the weight of the script.

[edit] Use whitespaces around operators

Whitespaces around operators increase code readability and make complex expressions easier to grasp.

[edit] Do not use the for-in loop on arrays

Use traditional for enumeration. Especially when looping over arrays returned by the getElementsBy... function family the usage of for-in will render you script non-working on Safari browsers.

[edit] Use addEvent/addHandler ( obj, type, fn )

When hooking an event handler to a DOM tree object use the functions addHandler, addClickHandler or addEvent (if you may want to remove it) for maximum browser compatibility. Do not try to assign function pointer to onevent properties directly!

[edit] Use importScript(pageName)

When including other javascript files do not use the document.write("<script>... construct, use the more compact and readable importScript(pageName) function.

[edit] Use var

While some browsers let you get away with using new variable without declaring them with var before, don't do it. Not properly declaring variables creates a slew of problems, trust me!

[edit] Don't be dumb about performance

Javascript is slow, but there is no need to make it slower. When constructing for loops avoid complex functions in the loop header which will be executed at each iteration.

Bad:

for( var i=0; NavFrame = document.getElementsByTagName("div")[i]; i++ )
{

Good:

var NavFrameList = document.getElementsByTagName("div");
for( var i=0; i < NavFrameList.length; i++ )
{
 NavFrame = NavFrameList[i];

Additionally the bad example will not fully iterate arrays with undefined, 0, or "" elements!

[edit] How to construct URIs

If your script needs to construct a URI, make sure that it also works for page names that contain special characters such as the ampersand ("&"). Any parameter to some server-side script that is called through a URI must be properly encoded. Otherwise, the server-side script will not work as expected because it considers the ampersand a delimiter between multiple parameters. If the page name contains an ampersand, the server-side script will get confused.

Example

• A call to the CheckUsage tool through a URI for Image:Forest & Bird headquarters.jpg, without encoding the page name: this looks for something named "Forest_".
• The same call with the page name properly encoded as "Forest_%26_Bird_headquarters.jpg" finds the uses of that image.

The same is true for all URI parameters, not just image names, but also user names or any other parameter.

You can use the function encodeURIComponent to ensure that URI parameters are properly encoded.

To get a page title, properly encoded for direct usage in a URI, you can use

var encoded_page_title = encodeURIComponent (wgTitle.split (" ").join ("_"));

Do not use wgTitle directly!

(Replacing blanks by underscores, as in the snippet above, is just to beautify the resulting URI a little bit. It's not strictly necessary, encodeURIComponent would otherwise encode the blanks as "%20". An underscore just looks better, and works because the MediaWiki software treats blanks in page names as underscores. But using just encodeURIComponent (wgTitle) also works.)

[edit] Add the talk page to Category:User scripts

Then other people will be able to find and use it.

[edit] Take a look at MediaWiki:Common.js

Make yourself familiar with the helper functions provided by Mediawiki and Commons. Avoid code duplication! When you discover a bug in a helper function or need extended functionality contact a developer, a fix of a global helper function will benefit more users than a local workaround.

If you were to use Ajax, use the global ajax functions, like sajax_init_object(), not XmlHttpRequest.