Moodle JavaScript Cookbook

To begin with, we will create a subfolder named cook within our Moodle installation where we will put all the files we will work with throughout the book.

Next we will create the template PHP file blank.php, with the following content:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->set_url('/cook/blank.php');
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

We now have our template saved at /path/to/moodle/cook/blank.php.

To test this new template, we can load it in a web browser and check if all is well. Assuming we have a web server running with Moodle served at the base URL http://localhost/moodle, we can load the following URL to test our new template: http://localhost/moodle/cook/blank.php.

If the template is set up correctly, we will see a basic page with standard header and footer, similar to the following:

We begin by opening the PHP tags in the standard way, using <?php.

Note that we have not used the shorthand notation of <?, as this goes against the Moodle programming guidelines and also against general good practice.

Next, we must include Moodle's global configuration file. The inclusion of this file sets up the requisite Moodle programming environment, including two global variables we will make use of: $PAGE and $OUTPUT.

$PAGE is defined as a central store of information about the current page we are generating in response to the user's request.

The $PAGE object allows us to start defining the properties of the page, namely the context and the URL. The context of the page is the scope of the page, that is, where in the Moodle system it is being used. We are using the System context; other examples are in the Course or Module context.

Next, we set the URL of the page. This mirrors our directory structure; so in this case we just set it to /cook/blank.php.

$OUTPUT is defined as an instance of core_renderer or one of its subclasses. Use it to generate HTML for output.

The $OUTPUT object allows us to generate the header and footer for our page, based on the current Moodle theme. This is done by calling the header and footer methods of the $OUTPUT object, and using echo to write them to the page.

After opening the PHP tag, we can begin inserting the PHP code. We use require_once to include the Moodle configuration file (this ensures that the file is included only once, and will halt execution of the page if the file is unavailable). The path to the configuration file is determined by using the dirname function to get the directory path to the current file (using the built-in __FILE__ constant), and then traversing up one directory (as we are in our cook subdirectory) to find the config.php file.

Next, we set the page context by calling the set_context method of the $PAGE object. This takes a context instance. We retrieve the instance for the system context by passing the CONTEXT_SYSTEM constant to the get_context_instance function.

The final usage of the $PAGE object is to set the page URL, which is done using the set_url method, passing in a web root relative URL path, which is /cook/blank.php in this case.

Next, we need to use the $OUTPUT object to generate the header and footer of the page. Both header and footer methods return HTML as a string, so we can use the echo construct to write these strings to the page.

Make a new PHP file named requirejs.php in the cook directory similar to the template in the previous recipe:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->set_url('/cook/requirejs.php');
$PAGE->requires->js('/cook/alert.js');
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

Next, we create the accompanying JavaScript file, alert.js, with the following content:

alert('Hello World!');

Now when we load the page in a web browser, we see that the JavaScript alert is displayed as shown in the following screenshot, proving to us that our code has loaded and executed correctly:

Note that we see the Home button, meaning that the footer of the page has loaded. This is because our code is executed at the end of the <body> tag.

We have created a page based on the blank template we created in the first recipe of this chapter. To this, we have added the following line:

$PAGE->requires->js('/cook/alert.js');

We are making use of the Page Requirements Manager, $PAGE, which is an object that contains various methods for setting up additional components for a page. Here we have called the $PAGE->requires->js method, and passed the path to our .js file as a parameter.

Moodle then adds this script to the list of scripts to be included within the final rendered page. A <script> tag similar to the following will be inserted just before the closing <body> tag:

<script type="text/javascript" src="http://localhost/moodle/lib/javascript.php? file=%2Fcook%2Falert.js&amp;rev=1"></script>

This code must be included after the Moodle configuration file config.php has been included. This is where the $PAGE object is setup for us.

Once again, open the Moodle PHP file where we will add our .js file. We will use the simple example from the previous recipe as a basis, with the necessary changes:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->requires->js('/cook/alert.js', true);
$PAGE->set_url('/cook/requirejs_head.php');
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

Now when we load the page, we see that our JavaScript alert is executed immediately, assuring us that our code is loading and executing correctly, as seen in the following screenshot:

Note that the page underneath is blank at this stage, as our JavaScript code is being run from the <head> tag, before the rest of the page has loaded.

You will notice that this code is almost identical to that of the previous recipe. The key difference here is the parameters we have passed to the $PAGE->requires->js method. We have passed a second optional parameter which determines whether or not the <script> tag will be rendered within the document's <head> tag. In this case, we set it to true to ensure that the <script> tag is rendered as such.

We have called $PAGE->requires->js again, this time with two parameters. The first is the path to the .js file we wish to include. The second is a Boolean value which specifies whether or not to include the file from within the <head> tag of the HTML page.

The <script> tag that is rendered to the document is identical to that of the previous recipe, with the crucial difference that it is rendered within the <head> tag, rather than at the end of the <body> tag.

Set up a page requirejs_init.php with the following content:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->set_url('/cook/requirejs_init.php');
$PAGE->requires->js('/cook/requirejs_init.js');
$PAGE->requires->js_init_call('hello');
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

Set up the accompanying JavaScript file, requirejs_init.js, with the following content:

function hello(Y)
{
alert('Hello World!');
}

Now when we load the page, we see that our JavaScript alert is executed, assuring us that our code is loading and executing correctly, as seen in the following screenshot:

We wish to make a call to our JavaScript function named hello. This is achieved with the js_init_call method. We pass one parameter, which is a string containing the name of the function we wish to call, which is hello.

When the document is rendered, the js_init_call method ensures that a call to our JavaScript function is generated. This example will generate the following JavaScript:

hello(Y);

This JavaScript is then included inside a <script> tag at the end of the <body> tag of the final page.

Create a new PHP file requirejs_init_data.php with the following content:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->set_url('/cook/requirejs_init_data.php');
$PAGE->requires->js('/cook/requirejs_init_data.js');
$PAGE->requires->js_init_call('hello',
array('Hello', $USER->username));
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

This code sets up a simple Moodle page and includes a JavaScript file requirejs_init_data.js containing the following basic "Hello World" function that we will call, which accepts three parameters.

Note that the first parameter Y, which is an instance of the YUI object, is automatically passed to our function by the Page Requirements Manager.

The two subsequent parameters are strings to be passed to the function: message and username:

function hello(Y,message,username)
{
alert(message + ', ' + username);
}

Now when we load the page, we see that our JavaScript alert is executed, displaying the message we passed along with the current user's username (admin):

Just after the call to $PAGE->requires->js, add the following code:

$PAGE->requires->js_init_call('hello', array('Hello', $USER->username));

The first parameter is a string containing the name of the JavaScript function we wish to call, which is hello in this case.

The second parameter is a PHP array of values that are passed on to the JavaScript function in the order in which they are defined.

The use of an array here allows the js_init_call method to support an arbitrary number of arguments, two in this case: the message and username.

We have used the Page Requirement Manager to register the name of the function we wish to be called and passed two additional parameters required by the function inside a PHP array.

When the document is rendered, the following JavaScript will be generated inside a <script> tag just before the end of the <body> tag:

hello(Y, "Hello", "admin");

Open the PHP file that contains the embedded JavaScript and locate the start and end <script> tags.

Add the following code immediately after the opening <script> tag:

<script language="JavaScript" type="text/javascript">
//<![CDATA[

Add the following code immediately before the closing <script> tag:

//]]>
</script>

The CDATA tag we have used informs the XHTML rendering engine that it should treat anything inside as arbitrary data, and not to attempt to parse it as if it were valid XHTML markup.

Additionally, to avoid a conflict with JavaScript syntax, the lines on which the CDATA tags reside have been commented out with double forward slashes (//).

In this example, we will retrieve the built-in Moodle language string course and show that it is available from our JavaScript code by displaying it with the alert function.

We start once again with a basic Moodle page and associated .js file:

<?php
require_once(dirname(__FILE__) . '/../config.php');
$PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
$PAGE->set_url('/cook/requirejs_init_lang.php');
$PAGE->requires->js('/cook/requirejs_init_lang.js');
$PAGE->requires->string_for_js('course', 'moodle');
$PAGE->requires->js_init_call('lang');
echo $OUTPUT->header();
echo $OUTPUT->footer();
?>

As you can see, this code registers a call to the function lang which has been defined in the associated .js file:

function lang(Y)
{
alert(M.str.moodle.course);
}

Now when we load the page, we see that our JavaScript alert is executed, displaying the language string value we set up, as seen in the following screenshot:

We have included our .js with the method now familiar — $PAGE->requires->js.

After this line comes a new feature of the Page Requirements Manager, the string_for_js function:

$PAGE->requires->string_for_js('course', 'moodle');

Finally, we refer to this language string from our JavaScript code:

alert(M.str.moodle.course);

We call the string_for_js method with two parameters: the name of the string we wish to retrieve and the location of this string. In this example, we are retrieving the language string for course from the core Moodle language file.

Now this string is made available to us as part of Moodle's global JavaScript namespace (M) in the format, M.str.<module name>.<string name>. In our example, this is M.str.moodle.course.

Using this method, the strings we have set up will be available to all subsequent JavaScript code. If we had simply passed this string as a parameter to the JavaScript function, it would only be available inside that function. If we required it to be available within additional functions, we would have to repeat the process, making copies of the string and passing those to the additional functions resulting in unnecessarily inefficient code.