Drag and drop question type flash development

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

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.

Flash requirements

There are three different modes for the Flash movie, documented below in further depth in the technical section

Teacher defines a question (new or editing existing)

The flash object must load the background image previously selected by the teacher, and allow them to create and position hotspots on it.

The hotspots must be either made with a polygon tool, allowing them to draw lines until the shape is completed, or an ellipsis tool, which is either a circle or an ellipse.

The teacher must then define mappings between the drag targets (previously selected by the teacher) and the hotspots they have created, and define an optional 'snap point' if this configuration item has been selected.

Because Moodle requires question definition data to be in a $mform (Moodle form), the flash object must read from and write to the DOM to communicate. This is dtetailed further in the javascript section.

Student attempts a question

When the student is attempting the quiz, the flash movie will be loaded, and they will be able to drag the drag items onto hotspots on the background image. Depending on config, the drag items will snap to points or not. The flash movie must again use javascript to read from and write to the DOM.

Teacher or student view student's attempt

Given a list of hotspot definitions, the drag items, and the student's mappings, the flash object must present a rastered version of the student's attempt.

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' }
    );
 * The serialized form of this (that is stored in the form field) looks like:
 * id:6|filepath:path/to/file|alttext:some content here||id:7|filepath:path/to/file|alttext:some content here
 * that is, items are separated by ||, fields are separated by | and each field/value pair are split with :
 * Some values might include : but we just match the first one and take the rest of the string as the value.
 */
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
    );
 * The serialised form of this (that is stored in the form field) looks like:
 * id:6|shape:ellipse|geometry:1,4,6,6|snapx:6|snapy:7||id:7|shape:ellipse|geometry:1,4,6,8
 * In a very similar form to the other serialized forms.
 */
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 },
    );
 * The serialised form of this (that is stored in the form field) looks like:
 * hotspotid:6|mediaid:8||hotspotid:7|mediaid:9
 * In a very similar form to the other serialized forms.
*/
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': 6, '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},
    );
 * The serialised form of this (that is stored in the form field) looks like:
 * hotspotid:6|mediaid:8|x:12|y:13||hotspotid:7|mediaid:9|x:14|y:15
 * In a very similar form to the other serialized forms.
*/
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

Documentation

Drag and drop question type flash development

Contents

Preamble

Flash requirements

Teacher defines a question (new or editing existing)

Student attempts a question

Teacher or student view student's attempt

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