jQuery pre2.9

Moodle 2.8

Prior to Moodle 2.9, YUI is the recommended library for development of Moodle plugins or customisations. It is still possible to use jQuery in Moodle add-ons for these older Moodle versions.

In Moodle 2.9 and later it is recommended to use Javascript Modules and jQuery for all new javascript in both core and plugins.

Examples

Basic jQuery in add-on theme

1. create /theme/sometheme/lib.php file if it does not exist yet
2. add new function theme_sometheme_page_init to the lib.php file (replace 'sometheme' with real name of your theme)
3. use jQuery JavaScript in theme layout files

<?php // file: /theme/sometheme/lib.php function theme_sometheme_page_init(moodle_page $page) {

   $page->requires->jquery();

}

// near the end of file: /theme/sometheme/layout/general.php <script>

 $('.headermain').mouseover(function() {
   alert('yoopee');
 });

</script>

jQuery UI in add-on activity module

1. optionally add more jQuery plugins (not recommended because the same plugins in different add-ons may collide)
2. add necessary $PAGE->requires
3. use jQuery

<?php require('../../config.php');

// ... normal PAGE setup and access control

$PAGE->requires->jquery(); $PAGE->requires->jquery_plugin('ui'); $PAGE->requires->jquery_plugin('ui-css');

echo $OUTPUT->header(); ?>

   <button>A button element</button>

This is the default dialog which is useful for displaying information. The dialog window can be moved, resized and closed with the 'x' icon.

   <script>
       $(function() {
           $( "#dialog" ).dialog();
       });
   </script>

<?php echo $OUTPUT->footer();

jQuery UI in add-on block

1. add necessary requires in get_required_javascript() method in your block, do not forget to call it in parent too
2. use jQuery in blok html output


class block_html extends block_base {

   function get_required_javascript() {
       parent::get_required_javascript();

       $this->page->requires->jquery();
       $this->page->requires->jquery_plugin('ui');
       $this->page->requires->jquery_plugin('ui-css');
   }

   function get_content() {

       // ....

       $this->content->text .= '

<script>

 $(function() {
   $( "#progressbar" ).progressbar({
     value: 37
   });
 });

</script>';

       // ....
   }

Including your own plugins

Note: Your plugin your have a filename which includes its version number. This is the same as in the core jQuery project. This enables you to increment the version of your plugin when you make changes to it.

1. Place your jQuery plugin into mod/yourplugin/jquery/jquerymodule/
2. Add the plugin information to the plugins.php file
3. Use the plugin in your code

Add the plugin information to the plugins.php file

// file: mod/yourplugin/jquery/plugins.php $plugins = array(

   'yourplugin-jquerymodule' => array(
       'files' => array(
           'jquerymodule/jquery-somefilename-1.0.1.min.js',
       ),
    ),

);

Use the plugin in your code

<?php // file: /mod/yourplugin/lib.php // ... rest of file ... $PAGE->requires->jquery_plugin('yourplugin-jquerymodule', 'mod_yourplugin');

Overriding base jQuery UI theme

1. download new jQuery UI theme and extract it into theme/sometheme/jquery/custom-1.0
2. define new jQuery theme ui css plugin in theme/sometheme/jquery/plugins.php
3. overrider core 'ui-css' with 'yourtheme-ui-css'

<?php // file: theme/sometheme/jquery/plugins.php $plugins = array(

   'sometheme-ui-css' => array('files' => array('custom-1.0/jquery-ui-1.10.2.custom.min.css')),

);

<?php // file: /theme/sometheme/lib.php function theme_sometheme_page_init(moodle_page $page) {

   // There is no need to $page->requires->jquery() if the theme does not use jQuery.
   $page->requires->jquery_plugin('sometheme-ui-css', 'theme_sometheme');
   $page->requires->jquery_override_plugin('ui-css', 'sometheme-ui-css');

}

Backwards compatibility for scripts written for legacy jQuery versions

See jQuery Migrate plugin

$PAGE->requires->jquery(); $PAGE->requires->jquery_plugin('migrate');

// Incompatible code designed for 1.8.x jQuery should work now...

mymobile theme

See mymobile theme for more examples including custom jQuery plugin and integration with jQuery Mobile.

More information

Bundled plugins

Official Moodle distribution contains jQuery, jQuery UI and jQuery Migrate plugins.

jQuery plugin collisions

The loading order of plugins is defined by order of $PAGE->requires. If there are plugins with the same name the first $PAGE->require wins.

It is recommended to use plugin overrides only in themes because multiple overrides of the same plugin result in undefined behaviour. In general themes should have more freedom to add extra jQuery plugins, other Moodle plugins should ideally use only basic jQuery or jQuery UI.

jQuery plugin modifications

Files in jQuery plugins MUST NOT be changed, always create a new file with different name and update CSS and plugins.php if necessary and delete the old file.

jQuery versions

Only minor jQuery version updates can be done in STABLE branches. Add-on developers must revalidate compatibility after every major upgrade. Use official 'migrate' plugin if necessary, see example above.

Frequently asked questions

Can I serve jQuery from CDN?

No, because CDNs do not include all plugins and some do not support https. Use proxy caching such as Cloudflare instead.

I edited some file but the change is ignored, why?

Moodle and your browser caches Javascript, to circumvent this rename your Javascript file as shown here. Additionally you can use the developer console on Chrome or Firefox to disable caching for Javascript.

See above, files MUST NOT be updated in jQuery plugins, always create new files or directories. Moodle cache purging does not have any effect on jQuery plugins.

Can we remove YUI now?

No! YUI is the only recommended JS library in Moodle add-ons and core.

Can I use different jQuery version?

No. (Theoretically you might try jQuery plugin override to include some later minor revision.)

Could we have jQuery plugin dependencies?

No, order your $PAGE->requires manually.

Are there any performance costs when using jQuery?

Yes. Please consider using SimpleYUI for simple DOM manipulations or standard YUI widgets.

Can I use YUI loader to include jQuery?

No. Moodle jQuery support is not compatible with sandboxing.

Moodle complains when I disable slasharguments setting, why?

Please fix your server to be compatible with slasharguments, even IIS can support it now!

Why is jQuery UI split into two plugins?

This allows Moodle themes to override the jQuery UI CSS and images.

See also

• jQuery
• jQuery User Interface