Development:AJAX marking block

This page outlines the internal architecture of the AJAX marking block and how to extend it for new types of assignment.

Architecture

The block has a server side section of code written in PHP and a client side in javascript. The client is based on the YUI treeview widget and sends asynchronous messages to the server to retrieve the data which becomes the nodes of the tree. Each time a node is clicked to expand it, a new message is sent, with the response data parsed and made into the new sub-nodes.

HTML fallback

To aid accessibility, the block starts by loading a very basic HTML version so that if javascript is turned off either in the browser or the user's preferences, the block is still usable. This HTML version is normally not visible as the javascript acts to hide it immediately if possible.

File structure

The main lib.php file provides a base class which holds most of the useful functions. This is extended through inheritance when either ajax.php is accessed (each time an asynchronous request is sent) or html_list.php is included when the page is initially set up, providing an object which automatically collects submitted POST data and outputs the desired code once instantiated. This file also has a base class, module_base which is extended by each of the modules with a modulename_functions classin the modulename_grading.php file. All of these files are included as needed at the start and the instantiated objects are added to the main library class object as e.g. $AMB_AJAX_response->quiz so that their functions are available. The module objects will need to use many of the library functions, so a reference to the parent library object is passed in via the constructor and is used as $this->mainobject->useful_function().

The javascript.js file contains a collection of functions which are placed within the YAHOO.ajax_marking_block namespace. Some are part of YAHOO.ajax_marking_block.tree_base which is an extended version of the YAHOO.widget.TreeView widget that gets instantiated once for the main tree and once for the configuration tree via a factory function.

Plugins

The block is designed to allow new assessment types to be added dynamically. Rach new type will need to provide two files: modulename_grading.php and modulename_grading.js, whic can be placed either in the /block/ajax_marking folder or in the /mod/modulename folder.

To see how these work, take the assignment_grading files as examples.

PHP

The php file will need the following functions as a minimum:

Javascript

Using the assignment module as an example, the javascript file will need to use the YAHOO.ajax_marking_block.modulename namespace and will have to add the following features:

Make a new namespace for the module:

 YAHOO.ajax_marking_block.assignment = {};

The following functions (in no particular order) all use this namespace and must be included even if empty unless otherwise stated.

Provide arguments for the pop up window that the grading will happen in. The main thing to change here is the height and width so that the grading interface is visible.

 YAHOO.ajax_marking_block.assignment.pop_up_arguments  = function(clicked_node) {
     return 'menubar=0,location=0,scrollbars,resizable,width=780,height=630';
 };

Provide the URL for the pop up window. This will usually involve some combination of the student's userid and the assessement id or coursemodule id. This data is saved in the data attribute of the clicked node and is passed through to this function. You will need to make sure it is passed through by the PHP code on the server.

 YAHOO.ajax_marking_block.assignment.pop_up_opening_url = function (clicked_node) {
     return '/mod/assignment/submissions.php?id='+clicked_node.data.aid+'&userid='+clicked_node.data.sid+'&mode=single&offset=0';
 };

The pop up window needs to be closed after grading has finished, which a small piece of javascript carries out. It does this by checking to see if the URL has changed to the one signifying that your grades have been saved, so grade some work, press 'save' and look to see the URL, which you put in this function.

 YAHOO.ajax_marking_block.assignment.pop_up_closing_url = function (clicked_node) {
     return '/mod/assignment/submissions.php';
 };

There may be a need to send more than just the standard user id and assessment item id with the AJAX request in order to specify what's needed. See the quiz module for an example, where the quiz id and question id are needed as well as the user id. Leave it as below if not required.

 YAHOO.ajax_marking_block.assignment.extra_ajax_request_arguments = function (clicked_node) {
     return true;
 };

You then need to provide code that will alter the pop up's contents so that when the submit button is clicked, the tree nodes are updated. The function below will be run every second from the point at which the pop up is opened until it completes successfully. It aims to test the loaded portion of the DOM to see whether the buttons that need altering are present, then adds an onclick function which will update the tree.

 YAHOO.ajax_marking_block.assignment.alter_popup = function(node_id) {
 
     var els = ;
 
     if (YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName) {
 
         els = YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName('submit');
         // the above line will not return anything until the pop up is fully loaded
 
         if (els.length > 0) {
             var functionText   = "return YAHOO.ajax_marking_block.main_instance.remove_node_from_tree(-1, '";
                   functionText += node_id+"', false); ";
 
             els[0]["onclick"] = new Function(functionText);
 
             // cancel the timer loop for this function
             window.clearInterval(YAHOO.ajax_marking_block.timerVar);
         }
     }    
 }