Development:JavaScript guidelines - Revision history

TimHunt: /* See also */

2008-11-11T00:00:08Z

TimHunt at 23:59, 10 November 2008

2008-11-10T23:59:52Z

← Older revision		Revision as of 23:59, 10 November 2008
Line 114:		Line 114:
	* [http://developer.yahoo.com/yui/ YUI documentation]		* [http://developer.yahoo.com/yui/ YUI documentation]
	* [[Development:Unobtrusive_Javascript]]		* [[Development:Unobtrusive_Javascript]]
	* [[Development:~~Javascript_functions~~]]		* [[Development:JavaScript_functions]]
	* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]		* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

TimHunt: /* Advice on how to chunk your JavaScript */

2008-10-31T08:36:11Z

Advice on how to chunk your JavaScript

← Older revision		Revision as of 08:36, 31 October 2008
Line 98:		Line 98:

	(At some point, Moodle may implement a system for automatically combining different JavaScript files from different plugins, for example automatically combining all the JavaScript required by all currently enabled filters, but this should be transparent to the rest of the code.)		(At some point, Moodle may implement a system for automatically combining different JavaScript files from different plugins, for example automatically combining all the JavaScript required by all currently enabled filters, but this should be transparent to the rest of the code.)


			==Other points==

			When JavaScript is turned on, the class name 'jsenabled' will be added to the body tag of the page.

	==Testing==		==Testing==

TimHunt at 04:43, 26 September 2008

2008-09-26T04:43:00Z

← Older revision		Revision as of 04:43, 26 September 2008
Line 11:		Line 11:

	Try to add as few things as possible to the global JavaScript name-space - use a few objects in the global name-space with properties and methods. An extreme example is the YUI libraries which only add a single YAHOO object to the global scope. Everything else is contained within that.		Try to add as few things as possible to the global JavaScript name-space - use a few objects in the global name-space with properties and methods. An extreme example is the YUI libraries which only add a single YAHOO object to the global scope. Everything else is contained within that.

			Load and execute the JavaScript as late as possible. Since our page should work without JavaScript, load the scripts, and initialise your event handlers from the page footer. If you do this, the page appears to load much more quickly. The user can start to read the page, and by the time they have moved the mouse pointer over your control and click (or whatever), the JavaScript will have had time to load and be ready for them.

			Use as few different .js files as possible. Each separate file load that the browser performs has a big overhead. On the other hand, don't include irrelevant JavaScript code. Code that is loaded but never used is a waste of time. Getting this right involves taking an informed decision about how to chunk your JavaScript.

	The rest of this page explains how you can achieve these goals.		The rest of this page explains how you can achieve these goals.
Line 28:		Line 32:
	require_js(array('yui_yahoo','yui_event', 'yui_connection'));		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 ~~neatly inside~~ the ~~<head>~~. ~~However, it is not~~ really ~~a problem if you have~~ to ~~call require_js later. In that case it will just immediately output 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~~.)		By default, these libraries will be included by adding <script src=...> tags to the footer of the HTML page. This improves performance. If you really need some JavaScript to be loaded before the rest of the page, you can set the optional second argument of require_js to true (note that this only applies from Moodle 2.0 onwards. In Moodle 1.9, require_js put the <script> tags in the header.

	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.		require_js 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==		==What should go in your .js files==
Line 86:		Line 90:
	);		);
	print_js_config($config, 'qengine_config');		print_js_config($config, 'qengine_config');

			==Advice on how to chunk your JavaScript==

			The aim is to only require a few different .js files to be loaded by each page, while not including huge amounts of irrelevant JavaScript for the browser to parse and then ignore.

			Generally speaking, each component of Moodle (activity module, block, filter, ...) should just have one JavaScript file. You might make an exception to this if, for example, you have some JavaScript that your module uses all the time, and a lot of JavaScript that is only used when your module is being edited. In this case, it would be sensible to make a second edit.js file.

			(At some point, Moodle may implement a system for automatically combining different JavaScript files from different plugins, for example automatically combining all the JavaScript required by all currently enabled filters, but this should be transparent to the rest of the code.)

	==Testing==		==Testing==
Line 98:		Line 110:
	* [[Development:Unobtrusive_Javascript]]		* [[Development:Unobtrusive_Javascript]]
	* [[Development:Javascript_functions]]		* [[Development:Javascript_functions]]
			* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

	[[Category:Developer]]		[[Category:Developer]]
	[[Category:Javascript]]		[[Category:Javascript]]
	[[Category:AJAX]]		[[Category:AJAX]]

TimHunt: /* Getting Moodle to load your JavaScript files */

2008-09-25T06:41:56Z

Getting Moodle to load your JavaScript files

← Older revision		Revision as of 06:41, 25 September 2008
Line 16:		Line 16:
	==Getting Moodle to load your JavaScript files==		==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:		There is a function '''require_js''' in lib/weblib.php. It takes one argument, which is either the path to the JavaScript file you want (which will automatically have $CFG->wwwroot prefixed). For example:

	require_js(~~$CFG->wwwroot .~~ '/question/qengine.js');		require_js('question/qengine.js');

	To simplify including the various YUI libraries, require_js recognises some short cuts like		To simplify including the various YUI libraries, require_js recognises some short cuts like

TimHunt at 13:47, 19 September 2008

2008-09-19T13:47:20Z

← Older revision		Revision as of 13:47, 19 September 2008
Line 86:		Line 86:
	);		);
	print_js_config($config, 'qengine_config');		print_js_config($config, 'qengine_config');

			==Testing==

			JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

	==See also==		==See also==

TimHunt: /* General principles */

2008-09-19T13:44:02Z

General principles

← Older revision		Revision as of 13:44, 19 September 2008
Line 9:		Line 9:

	The official JavaScript library for Moodle is [http://developer.yahoo.com/yui/ YUI]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.		The official JavaScript library for Moodle is [http://developer.yahoo.com/yui/ YUI]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

			Try to add as few things as possible to the global JavaScript name-space - use a few objects in the global name-space with properties and methods. An extreme example is the YUI libraries which only add a single YAHOO object to the global scope. Everything else is contained within that.

	The rest of this page explains how you can achieve these goals.		The rest of this page explains how you can achieve these goals.

TimHunt: /* General principles */

2008-09-19T13:02:10Z

General principles

← Older revision		Revision as of 13:02, 19 September 2008
Line 4:		Line 4:
	==General principles==		==General principles==

	Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript\|unobtrusive JavaScript]] and Development:Progressive_enhancement\|progressive enhancement]].		Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript\|unobtrusive JavaScript]] and [[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.		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.

TimHunt at 12:56, 19 September 2008

2008-09-19T12:56:56Z

← Older revision		Revision as of 12:56, 19 September 2008
Line 1:		Line 1:
	{{Moodle 2.0}}		{{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.		This page is currently just a brain-dump by Tim Hunt. Hopefully this is a useful starting point for [http://moodle.org/mod/forum/discuss.php?d=106312 discussion - please use this forum thread]. 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==		==General principles==

TimHunt: /* See also */

2008-09-19T12:55:21Z

← Older revision		Revision as of 00:00, 11 November 2008
Line 113:		Line 113:
	* [[Development:Coding\|The other coding guidelines]]		* [[Development:Coding\|The other coding guidelines]]
	* [http://developer.yahoo.com/yui/ YUI documentation]		* [http://developer.yahoo.com/yui/ YUI documentation]
	* [[Development:~~Unobtrusive_Javascript~~]]		* [[Development:Unobtrusive Javascript]]
	* [[Development:~~JavaScript_functions~~]]		* [[Development:JavaScript functions]]
	* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]		* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

← Older revision		Revision as of 12:55, 19 September 2008
Line 87:		Line 87:
	==See also==		==See also==

			* [http://moodle.org/mod/forum/discuss.php?d=106312 Forum thread for discussing this proposal]
	* [[Development:Coding\|The other coding guidelines]]		* [[Development:Coding\|The other coding guidelines]]
	* [http://developer.yahoo.com/yui/ YUI documentation]		* [http://developer.yahoo.com/yui/ YUI documentation]