Using jQuery with Moodle

Jump to: navigation, search

Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

jQuery support in Moodle 2.5

Moodle 2.5 contains jQuery and JQuery UI libraries in default installation, see jQuery for more developer documentation.

Before we begin

note: This is for Moodle versions before 2.5, please see jQuery doc for 2.5 onwards.

Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said, jQuery is very popular, and for what ever reason, it may be required.

I can't guarantee what you are doing will work nicely next to YUI, but hopefully it will!

So first up, make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript. Moodle can load JavaScript into either the pages head, or at the bottom of the page (footer). Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However, if you need code immediately within the page WHILE it is loading, then you will want to include it in the head.

Including jQuery within a plugin

Themes

Themes are not the easiest type of plugin to include jQuery, but if you are working on an installation that will be using a lot of customised code, then probably it is the best place.

  1. Open the theme you want to add jQuery to in a file browser and if there isn't already a javascript directory create one.
  2. Copy the jQuery files you want to make use of into the javascript directory of the theme.
  3. Open the themes config.php in your favourite editor (Notepad)
    • If you want to load your jQuery into the footer [recommended] then locate $THEME->javascripts_footer...
    • If you want to load it into the header then located $THEME->javascripts...
    • If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
  4. Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

  • moodle/theme/standard/javascript/jquery-1.4.2.min.js
  • moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:

// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

  1. Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
  2. Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to theme/javascript.php?...type=footer. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

Blocks and modules

This is much simplier than including jQuery from within a theme.

  1. Create a javascript directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
  2. Copy the jQuery files into the javascript folder.
  3. Add the following lines of php into every file which will make use of jQuery.
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.

$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);

Potential problems

You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure it complies.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is HIGHLY recommended to use YUI for everything possible.

More information

For more information on how to use JavaScript within Moodle 2.0 please see JavaScript guidelines