Development:JavaScript guidelines
Template:Moodle 2.0 This page is currently just a brain-dump by Tim Hunt. Hopefully this is a useful starting point for discussion. If we can all agree on something, then they will become actual coding guidelines, and we can fix up some of the more horrific things Moodle currently does with JavaScript.
General principles
Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in the principle of unobtrusive JavaScript or Development:Progressive_enhancement|progressive enhancement]].
Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.
The official JavaScript library for Moodle is YUI. That may not be your favourite, but it's the one that was chosen after some careful research, so live with it.
The rest of this page explains how you can achieve these goals.
Getting Moodle to load your JavaScript files
There is a function require_js in lib/weblib.php. It takes one argument, which is the URL of the JavaScript file you want, which will normally start with $CFG->wwwroot. For example:
require_js($CFG->wwwroot . '/question/qengine.js');
To simplify including the various YUI libraries, require_js recognises some short cuts like
require_js('yui_yahoo');
The full list of recognised short cuts is in lib/ajax/ajaxlib.php. You can also call require_js with an array of libraries, to further save typing. For example:
require_js(array('yui_yahoo','yui_event', 'yui_connection'));
Wherever possible, you should arrange your code so you call require_js before the call to print_header. If you can do that, then Moodle builds up a list of the required libraries, and puts all the <script src="..." ...> tags inside <head>. However, it is not a big problem if you have to call require_js later. If you call require_js later, then it just outputs a <script src="..." ...> tag in the body of the page. (In fact there is a tricky third case, where code executed in the middle of print_header calls require_js, and that works fine too.)
require_js also keeps track of which files have been included, and ensures that each one is only included once, like the PHP require_once directive.
What should go in your .js files
In almost every case, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed.
Getting variables from PHP to JavaScript
Sometimes your JavaScript code will need to refer to values that are only obtainable in PHP code. For example $CFG->wwwroot, or a language string obtained using get_string. ...
