AJAX

AJAX (Asynchronous Javascript and XML) is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, Javascript, CSS and the XMLHttpRequest object amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

Ajax in Moodle

Moodle 2.9

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:

1. No new ajax scripts need auditing for security vulnerabilities
2. Multiple requests can be chained in a single http request
3. Strict type checking for all parameters and return types
4. New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

1. Write or find an existing web service function to handle the ajax interaction: See Web_services
2. White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
3. Call the web service from javascript in response to a user action:

Example calling core_get_string: require(['core/ajax'], function(ajax) {

   var promises = ajax.call([
       { methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
       { methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
   ]);

  promises[0].done(function(response) {
      console.log('mod_wiki/pluginname is' + response);
  }).fail(function(ex) {
      // do something with the exception
  });

  promises[1].done(function(response) {
      console.log('mod_wiki/changerate is' + response);
  }).fail(function(ex) {
      // do something with the exception
  });

});

Note: This example chains to separate calls to the core_get_string webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

To update parts of the UI in response to Ajax changes, consider using Templates

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: AJAX pre 2.9

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:

1. Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
2. Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
3. The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
4. After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.

1. Add 'loginrequired' => false to the service definition in db/services.php
2. Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.

The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

See also

• AJAX pre 2.9
• Templates
• Javascript Modules
• Javascript FAQ
• Javascript
• Debugging AJAX with Firebug

• Ajax: A New Approach to Web Applications, the original Ajax article by Adaptive Path (This link is now dead, but the article is on the Internet Archive)
• AJAX: Getting Started article on developer.mozilla.org
• 10 places you must use AJAX by Adam Bosworth
• Considering Ajax, Part 1: Cut through the hype from IBM developerworks
• Wikipedia article on AJAX
• How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles
• AJAX loading icon generator