How to create a YUI 3 module

This document explains how to create a YUI 3 module in Moodle.

The two ways to write a YUI 3 module

There is two way to write a a YUI 3 module. Following an explanation by Sam Hemelryk.

The static module

The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature. If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

The YUI3 Moodle Module

This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a yui directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named. Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g./local/myplugin/yui/mymodule/mymodule.js The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

Static module quick start

1. Create a module.js file somewhere

2. The two way Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)

         //example:
         case 'core_rating':
                   $module = array('name'     => 'core_rating',
                                   'fullpath' => '/rating/module.js',
                                   'requires' => array('node', 'event', 'overlay', 'io', 'json'));

b- the file is in a local plugin: the first line of your module should be

M.local_xxx = {

xxx being your plugin directory name.

3. Write the module.js

 M.local_hub={
   Y : null,
   transaction : [],
   init : function(Y){
       alert('hub module initialisation');
       this.Y = Y;
   },
 }

4. Call this module. It can not be in a php renderer script, where you call the renderer seems the best

   $PAGE->requires->js_init_call('M.local_hub.init'); 

You should now have loaded and called your first YUI 3 module in Moodle.

5. Now to load it with some other YUI modules

   $jsmodule = array(
               'name' => 'local_hub',
               'fullpath' => '/local/hub/module.js',
               'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
   $PAGE->requires->js_init_call('M.local_hub.init',
                null, false, $jsmodule);

6. Pass parameter to the init function

PHP:

   $PAGE->requires->js_init_call('M.local_hub.init',
                   array('this is the param1 value'), false, $jsmodule);

JS:

   init : function(Y, params){
       alert(params);
       ....
   }