Latest revision as of 15:55, 27 January 2010

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Template:Infobox Project Template:Moodle 2.0

Goals

standardise usage of Javascript code in Moodle
improve performance
improve and simplify JS related APIs

API overview

Types of JS code in 1.9:

JS scripts linked from page head
JS linked and executed from page head
inline Javascript
global JS variables

Overview of JavaScript usage in 2.0

all JS stored in one global M namespace
majority of JS logic moved into page footer
loading of javascript modules handled by YUI3 loader
all plugins support module.js files
most JS is initialised through $PAGE->requires->js_init_call()
full migration to YUI3, YUI2 modules are loaded on demand only

Sample usage of JavaScript in module

Description of M namespace

Since Moodle 2.0 all JavaScript code, configuration data and runtime data are available through the global M object. All plugins register themselves in the M namespace, this namespace may be divided into three parts:

basic structures and utility methods, string support, etc. - M.util.*, M.cfg, M.yui.* (defined inline or in /lib/javascript-static.js)
core subsystems such as groups, roles, blocks - M.core_group.*, M.core_role.* (defined in various JS files or module.js in each core subsystem)
plugin modules such as forum, spamcleaner report, etc. - M.mod_forum.*, M.report_spamcleaner.* (defined in /mod/forum/module.js, /admin/report/spamcleaner/module.js)

The recommended strategy is to define one or more init functions in the plugin namespace such as M.mod_forum.init_view_page() and use it as the interaction point between PHP and JS code. The init function is called via: $PAGE->requires->js_init_call('M.mod_forum.init_view_page', $options); This function makes sure the appropriate JavaScript files are loaded and the init method is executed from the page footer after full initialisation of YUI library.

Performance improvements

New script serving similar to themes framework significantly improves caching (elimination of a large number of HTTP requests) and enables compression. Developers will need to disable caching or manually purge server caches. (Note: this feature is not in CVS yet, but the API is finished.)

Migration and code upgrade steps

study how to use YUI3
go through old plugin code and migrate all inline JS code to new file module.js in your plugin directory
convert YUI2 calls to YUI3 (some modules are not available in YUI3, fortunately YUI2 modules are usable from YUI3)
use $PAGE->requires->js_init_call() to integrate JS with your html markup generated from PHP

Migration to YUI3

Deprecated coding style

do not add JavaScript code directly to the markup - instead create init function that adds all necessary event handlers and DOM modifications
do not use general JS files - instead use new YUI3 modules stored in module.js files
do not create global variables to pass data from PHP to JS code - instead use parameters of init functions
do not add extra script links from PHP - instead use YUI3 loading of modules from JS code
do not use YUI2 modules if equivalent YUI3 modules already exit
instead of direct DOM modifications use YUI3 methods

@@ Line 11: / Line 11: @@
 =Goals=
-* standardised usage of Javascript code in Moodle
+* standardise usage of Javascript code in Moodle
-* improved performance
+* improve performance
 * improve and simplify JS related APIs
@@ Line 18: / Line 18: @@
 Types of JS code in 1.9:
-# JS scripts linked from page head - current javascript-static
+* JS scripts linked from page head
-# JS linked and executed from page HEAD
+* JS linked and executed from page head
-# inline Javascript
+* inline Javascript
-# global JS variables
+* global JS variables
-Proposed JS usage in 2.0
+Overview of JavaScript usage in 2.0
-* majority of JS logic is moved into page footer
+* all JS stored in one global M namespace
-* use YUI3 features and coding style as much as possible
+* majority of JS logic moved into page footer
-* load all large chunks of JS code as YUI3 modules on the fly - by default stored in mod/mymod/module.js, registered via $PAGE->requires->js_module('mymod'), used by Y.use('mod_mymod')
+* loading of javascript modules handled by YUI3 loader
-* include short JS init code in page footer - the JS code itself should be stored as string and accessed via plugin renderer, $PAGE->requires->js_init_code()
+* all plugins support module.js files
-* new global M instance, all JS modules functions are accessed through this global object
+* most JS is initialised through $PAGE->requires->js_init_call()
-* new global Y instance, initialised in page footer, can not be used in included scripts in top scope
+* full migration to YUI3, YUI2 modules are loaded on demand only
-* JS scripts included from page head can not use YUI2/3 at load because YUI loader is not initialised yet
-* YUI2 is not loaded by default, loading is done via YUI3 only
-Deprecated usage:
+=Sample usage of JavaScript in module=
-* no inline javascript (->now()) support in $PAGE->requires, instead events are registered via special function, other DOM manipulations are done in JS init code or through function calls in footer
-* no YUI2 libraries loaded by default, need to do Y.use('yui2-dom') before accessing old YAHOO global object.
-=Examples=
-=Code migration=
+=Description of M namespace=
-=Performance=
+Since Moodle 2.0 all JavaScript code, configuration data and runtime data are available through the global M object. All plugins register themselves in the M namespace, this namespace may be divided into three parts:
+# basic structures and utility methods, string support, etc. - '''M.util.*''', '''M.cfg''', '''M.yui.*''' (defined inline or in /lib/javascript-static.js)
+# core subsystems such as groups, roles, blocks - '''M.core_group.*''', '''M.core_role.*''' (defined in various JS files or module.js in each core subsystem)
+# plugin modules such as forum, spamcleaner report, etc. - '''M.mod_forum.*''', '''M.report_spamcleaner.*''' (defined in /mod/forum/module.js, /admin/report/spamcleaner/module.js)
+The recommended strategy is to define one or more ''init'' functions in the plugin namespace such as '''M.mod_forum.init_view_page()''' and use it as the interaction point between PHP and JS code. The init function is called via: <code php>$PAGE->requires->js_init_call('M.mod_forum.init_view_page', $options);</code> This function makes sure the appropriate JavaScript files are loaded and the init method is executed from the page footer after full initialisation of YUI library.
+=Performance improvements=
+New script serving similar to themes framework significantly improves caching (elimination of a large number of HTTP requests) and enables compression. Developers will need to disable caching or manually purge server caches. (Note: this feature is not in CVS yet, but the API is finished.)
+=Migration and code upgrade steps=
+# study how to use YUI3
+# go through old plugin code and migrate all inline JS code to new file module.js in your plugin directory
+# convert YUI2 calls to YUI3 (some modules are not available in YUI3, fortunately YUI2 modules are usable from YUI3)
+# use $PAGE->requires->js_init_call() to integrate JS with your html markup generated from PHP
+==Migration to YUI3==
+==Deprecated coding style==
+# do not add JavaScript code directly to the markup - instead create ''init'' function that adds all necessary event handlers and DOM modifications
+# do not use general JS files - instead use new YUI3 modules stored in module.js files
+# do not create global variables to pass data from PHP to JS code - instead use parameters of ''init'' functions
+# do not add extra script links from PHP - instead use YUI3 loading of modules from JS code
+# do not use YUI2 modules if equivalent YUI3 modules already exit
+# instead of direct DOM modifications use YUI3 methods
 =Links=
-* [[Development:Create_YUI3_Module_For_Moodle]]
+* [[Development:JavaScript FAQ]]
+* [[Development:Create YUI3 Module For Moodle]]

Documentation

Development:JavaScript usage guide: Difference between revisions