Drag and drop question type flash development

Preamble

I have a project where the need has arisen to be able to define drop targets for this question type which are not just rectangular - ellipses and polygonal targets are also needed.

After much discussion, we decided this was going to be far too hard to do in Javascript and we should use flash instead. After initially planning to add a flash only mode to the existing drag & drop question type, I decided to write a new flash only one from scratch.

The teacher will be given a flash object to define the drop targets and the mappings between them and the drag targets, and the student will be presented with a similar interface.

Technical Details

Database changes

Tables

question_flashdd

field	notes
id	sequence
questionid	fk to question
snaptopoints	boolean
backgroundpath	path to use (coursefiles url - this will change to an fk to file in 2.0)

question_flashdd_hotspot

field	notes
id	sequence
questionid	fk to mdl_question
shape	polygon or ellipse
geometry	Blob of serialised data
snapx (nullable)	x point to snap to
snapy (nullable)	y point to snap to

question_flashdd_media

field	notes
id	sequence
questionid	fk to question
filepath	coursefiles (will be upgraded to file id in 2.0)
alttext	optional alt text to display

question_flashdd_mapping

field	notes
id	sequence
questionid	fk to question
hotspotid	fk to question_flashdd_hotspot
mediaid	fk to question_flashdd_media

Flash/Javascript communication

Rationale

I had originally thought that the best way to communicate between the Flash object and Moodle would be the use of XMLHttp Requests, but after writing the Matrix Question type and having a better understanding of the Question API, I realise that this is not really the best approach, or even a particularly sound one. For an example of why not, imagine the case of creating a new question. The question record gets inserted by the question API rather than the question type - which means that the XMLHttp handler would be faced with the situation of being sent hotspot and media mapping data before the question is actually saved into the database.

Thus, it makes a lot more sense to just use forms as Moodle expects, and get Flash to read from, and write to, hidden form fields.

There are three different modes the Flash object must behave in:

Definition mode (teacher defining where the hotspots are and which items drag to them)
Test mode (student attempting question)
Review mode (student or teacher reviewing a rendered version in read only mode)

Example Javascript

var formname = null; // set by inline JS in the form definition

/**

* add a new hotspot to the list
*
* @param int id new unique id for this hotspot (not persistent - will be replaced by moodle on save)
* @param string shape currently just ellipse or polygon
* @param string geometry whatever data needs to be saved to define the hotspot - will just be saved as is and passed back to flash in this form next time
*
* @return boolean success or failure
*/

function addHotspot(id, shape, geometry, snapx, snapy) { }


/**

* update an existing hotspot definition
*
* @param int id new unique id for this hotspot (not persistent - will be replaced by moodle on save)
* @param string shape currently just ellipse or polygon
* @param string geometry whatever data needs to be saved to define the hotspot - will just be saved as is and passed back to flash in this form next time
*
* @return boolean success or failure
*/

function updateHotspot(id, shape, geometry, snapx, snapy) { }


/**

* delete a hotspot from the list
*
* @param int id the id of the hotspot to be deleted - this is whatever was added with addHotspot, or read with getHotspots
*
* @return boolean success or failure
*/

function deleteHotspot(id) { }


/**

* adds a new mapping to the list of dragitems to hotspots
*
* @param integer dragitemid
* @param integer hotspotid
*
* @return boolean success or failure
*/

function addMapping(dragitemid, hotspotid) { }


/**

* delete an existing hotspot mapping from the list
*
* @param integer dragitemid
* @param integer hotspotid
*
* @return boolean success or failure
*/

function deleteMapping(dragitemid, hotspotid) { }
/**

* adds a new mapping to the list of dragitems to hotspots
*
* @param integer dragitemid
* @param integer hotspotid (can be 0 if the student has dragged the item somewhere that isn't on a hotspot)
* @param integer x the actual point the student put the item on the x axis
* @param integer y the actual point the student put the item on the y axix
*
* @return boolean success or failure
*/

function addStudentMapping(dragitemid, hotspotid, x, y) { }


/**

* delete an existing hotspot mapping from the list
*
* @param integer dragitemid
* @param integer hotspotid (can be 0 if the student has dragged the item somewhere that isn't on a hotspot)
* @param integer x the actual point the student put the item on the x axis
* @param integer y the actual point the student put the item on the y axix
*
* @return boolean success or failure
*/

function deleteStudentMapping(dragitemid, hotspotid, x, y) { }
/**

* Fetch the path to the background image to use
*
* @return string full url to use to render the image
*/

function getBackground() { }
/**

* Fetch the option about whether to snap to points
*
* @return boolean on or off
*/

function getSnapOption() { }
/**

* Get the list of all the defined items to drag
* This will return an array of hashes like this:
   var dragitems = Array(
       { 'id': 6, 'filepath': 'fullurl', 'alttext': 'optional hint on hover' },
       { 'id': 7, 'filepath': 'fullurl', 'alttext': 'optional hint on hover' },
       { 'id': 8, 'filepath': 'fullurl', 'alttext': 'optional hint on hover' }
   );
*/

function getDragItems() { }
/**

* Get the list of hotspots that are currently defined and saved in Moodle.
* This will return an array of hashes like this:
   var hotspots = Array(
       { 'id': 6, 'shape': 'ellipse', 'geometry': '1,4,6,6', 'snapx': 6, 'snapy', 7 }, // circle
       { 'id': 7, 'shape': 'ellipse', 'geometry': '1,4,6,8' }, // ellipse
       { 'id': 8, 'shape': 'polygon', 'geometry': '1,4,6,6' }, // square
       { 'id': 8, 'shape': 'polygon', 'geometry': '1,4,6,6,8,9,0,5,2' } // totally whatck shaped polygon
   );
*/

function getHotspots() { }
/**

* Get the list of mappings that currently exist between Drag items and Hotspots
* This will return an array of hashes like this:
   var mappings = Array(
       { 'hotspotid': 6, 'mediaid': 8 },
       { 'hotspotid': 7, 'mediaid': 9 },
       { 'hotspotid': 8, 'mediaid': 10 },
       { 'hotspotid': 9, 'mediaid': 11 },
   );

/

function getMappings() { }


/**

* Get the list of student mappings that currently exist between Drag items and Hotspots
* This will return an array of hashes like this:
   var mappings = Array(
       { 'hotspotid': 0, 'mediaid': 8, 'x': 12, 'y': 13 },
       { 'hotspotid': 7, 'mediaid': 9 , 'x': 14, 'y': 15},
       { 'hotspotid': 8, 'mediaid': 10 , 'x': 16, 'y': 17},
       { 'hotspotid': 9, 'mediaid': 11 , 'x': 18, 'y': 19},
   );

/

function getStudentMappings() { }

Teacher defines a new question

Flash needs filepaths and alt text of all the media used in this question, as well as information about the bavckground image, and some config data.

These items will all be already present in the form, and just need to be read.

I will write javascript methods to interface with the DOM that Flash can call to get and set properties of the form.

Everytime a new hotspot is added, or a drag item mapped to it, Flash must update the hidden fields in the question definition form, and it will do this by calling javascript methods I write that can write to the form.

Note: it's possible that the teacher can trigger a reload of the Flash object after they've already started defining hotspots. This means that it must always read not just the media definitions, but also check for existing hotspot and mapping definitions on load, even when adding a new question. Actually this simplifies things on the Flash side, because it means there's no difference between edit and add code.

Methods Used

addHotspot
updateHotspot
deleteHotspot
addMapping
deleteMapping
getBackground
getSnapOption
getDragItems
getHotspots
getMappings

Teacher edits an existing question

Exactly the same as the previous point.

Student attempting a question

This will use a subset of the available methods.

This can either be editing an attempt, or starting a new one, so the existing mapping definitions must be observed.

Methods Used

addStudentMapping
deleteStudentMapping
getBackground
getSnapOption
getDragItems
getHotspots
getStudentMappings

Student feedback

A read-only rendered version of the final results with the drag items marked to their places

Methods Used

getBackground
getSnapOption
getDragItems
getHotspots
getStudentMappings

Teacher reporting of student attempt

Exactly the same as the previous point

XML definition for communication between PHP and Flash (deprecated)

There are five different times that data needs to be sent between PHP and Flash. Each point in the following list, data needs to flow in both directions. XML will be used for both directions. Flash will make a HTTP POST to PHP, with one post var, 'xml' containing the data. For Flash to get data from PHP, it will make an HTTP GET request and the body of the response data will be the XML data.

Teacher defines a new question

Data from PHP to Flash

filename, filepath, and alt text of background image
an array of information about the draggable objects, filename, filepath and alt text of each
configdata (eg whether the snap flag is set)

Example XML:

<xml>

   <defdata>
       <background>
           <filename>stuff.jpg</filename>
           <url>http://moodle.domain.com/file.php?path=course/1/stuff.jpg</url>
           <alt>Some hover info about the background image</alt>
       </background>
       <dragobjects>
           <dragobject id="1">
               <filename>smallobject1.jpg</filename>
               <url>http://moodle.domain.com/file.php?path=course/1/smallobject1.jpg</url>
               <alt>Something that could be a hint about this drag item</alt>
           </dragobject>
           <dragobject>
               ...
           </dragobject>
       <configdata>
           <snap>true</snap>
       </configdata>
   </defdata>

</xml>

Data from Flash to PHP

The definitions of the hotspots
The matching of drag objects to hotspots

Example XML:

<xml>

   <defdata>
       <hotspots>
           <hotspot id="somethinguniquegeneratedbyflash">
               <type>(polygon|ellipsis)</type>
               <coords>x,y,x,y,x,y,x,y</coords> 
               <radii>3,6</radii> 
           </hotspot>
           <hotspot>
               ...
           </hotspot>
       </hotspots>
       <mappings>
           <mapping>
               <hotspot id="somethingunique" />
               <dragobject id="1" />
       </mappings>
   </defdata>

</xml>

Teacher edits the definition of an existing question

This is exactly the same as the above case, except that the <hotspots> and <mappings> sections are also included in the data from PHP to Flash.

Student attempting a question

Data from PHP to Flash

This has no new data from the above two examples, but does not include the <mappings> section.

Data from Flash to PHP

Flash just needs to send back the mappings that the student has selected.

Example XML

<xml>

   <defdata>
       <mappings>
           <mapping>
           <hotspot id="6" />
           <dragobject id="7" />
       <mappings>
   </defdata>

</xml>

Student feedback

We may need to generate a report for the student that does one of two things:

Shows them their generated image, with color indicators to show correctness
Shows them the image with the correct answers placed

In both cases, the entire definition needs to be sent from PHP to Flash, with one addition in the <mapping> section:

<xml>

   <defdata>
       ....
       <mappings>
           <mapping>
           <hotspot id="6" />
           <dragobject id="7" />
           <correct>true</correct>
       <mappings>
   </defdata>

</xml>

Teacher reporting of student attempt

This is exactly the same as the above case.

Notes

The first time the <hotspot> tag is sent is from Flash to PHP and will include the ID generated by Flash. All subsequent communication will include the ID that Moodle generates (an auto-increment database ID)

Documentation

Drag and drop question type flash development

Contents

Preamble

Technical Details

Database changes

Tables

question_flashdd

question_flashdd_hotspot

question_flashdd_media

question_flashdd_mapping

Flash/Javascript communication

Rationale

Example Javascript

Teacher defines a new question

Methods Used

Teacher edits an existing question

Student attempting a question

Methods Used

Student feedback

Methods Used

Teacher reporting of student attempt

XML definition for communication between PHP and Flash (deprecated)

Teacher defines a new question

Data from PHP to Flash

Data from Flash to PHP

Teacher edits the definition of an existing question

Student attempting a question

Data from PHP to Flash

Data from Flash to PHP

Student feedback

Teacher reporting of student attempt

Notes