Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

JavaScript usage guide

From MoodleDocs

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.

Javascript usage guide
Project state Work in progress
Tracker issue MDL-21240
Discussion n/a, developer chat only
Assignee Petr Škoda (škoďák) + feedback and ideas from Sam and Dongsheng, based on previous work of Nicolas and Tim

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:

  1. basic structures and utility methods, string support, etc. - M.util.*, M.cfg, M.yui.* (defined inline or in /lib/javascript-static.js)
  2. 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)
  3. 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

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

Migration to YUI3

Deprecated coding style

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

Links