Question Writer Manual/About Questions/Plugins/Plugin Interface

Plugin Question Requirement

Plugin Questions need to follow certain rules very closely in order to function correctly within the Question Writer environment.

Plugin Question Specification

Plugin Questions are Flash components and are created in exactly the same way. If you are not familiar with creating Flash MX components, there is a good tutorial at

http://www.flashcomponents.net/tutorials/triangle/triangle.html

Constructor

The following values are made available in the constructor:

this._maxScore (String, points for fully correct answer)

this._isFeedback (String, either true or false, indicates whether feedback is being displayed)

this._responseid (String, response name)

this._listener (String, path to listener)

For each response option, a symbol id will be provided in the variables,

this._option0, this._option1, this._option2 and so on.

For each response option, an identifier will be provided as Strings in the variables,

this._option0ident, this._option1ident, this._option2ident, and so on.

A number of tabIndex values will be provided as Strings in the variables,

this._option0TabIndex, this._option1TabIndex and so on.

Also, for each response option, an accessibility String will be provided in the variables,

this._option0access, this._option1access, this. _option2access, and so on

The name/value pairs specified in the parameters of the Plugin Question are also made available in the constructor. All the values are provided as strings.

Requirements

Your component should implement the following methods.

isFullyAnswered()

This method should return a boolean, true/false. It is primarily used when the user is required to answer all the questions on a page. Question Writer will use this method to ask the Plugin Question if the question can be regarded as being in a 'fully answered' state. Note, this state has nothing to do with the answer being correct, just that a full attempt has been made.

getAnswers()

This method should return an Array of Strings containing the score as the first element of the array followed by the current response(s) in subsequent elements of the array. If the responses relate to the options that have been passed into the question, the strings that represent these options are available in the constructor as the variables, this._option0ident, this._option1ident, this. _option2ident, etc.

If you aren't using options as your answers, then it is fine to return meaningful string(s) as the response(s). This must return an array of Strings - even if the question deals with numbers, it should convert those values to strings before returning them as answers.

The plugin should also use this function to store the answers to be used when question feedback is provided. It can do this by calling this method:

this.respObject.setPair(this._responseid+"answers",answerArray);

setAnswers(Array)

This method should set the state of the Plugin Question based on the answers in the Array. This array will either send an empty array (when no attempt has yet been made on the question), or will return the Array that it had previously received when calling the 'getAnswers' method.

If the plugin is shown as feedback, it must access the answers from a stored location using the following method,

answerArray=this.respObject.getPairValue(this._responseid+"answers");

　

A final requirement is that your Plugin Question should call this code when the state of the component changes.

eval(this._listener).updateFlash(this._responseid);

Sequence of events

This is the order in which events happen when the Plugin Question is placed on screen.

1. The user clicks the next button and moves onto a page that contains the question.
2. Question Writer places the question on screen, calling the Plugin Question's constructor.
3. Question Writer calls the setAnswers(Array) method. If this is the first time this instance is appearing on screen, the Array will be empty.
4. The user makes an attempt at the question
5. The question calls 'eval(this._listener).updateFlash(this._responseid);'
6. Question Writer calls 'getAnswer()' method and stores the array.
7. Repeat steps 4 – 6 many times.
8. The user clicks 'next' to move out of the page.
9. Question Writer removes the question from the screen, destroying all information apart from the last answers array, which it stores.

Packaging

To package your component, first need to create a blank flash file. Drag your component onto the stage and then delete it. Your component should then be present in the library. Compile the flash file (as version 8 or less) as a .swf and this file is your finished Plugin Question.

Filename

The filename must be the same name as the symbol used for the Flash component plus the file extension (.swf). The filename also contains additional parameters, as per the following example.

QWPQ-0-20-0-ComboBoxV1_7.swf

First Parameter: (0) - This tells Question Writer how much on-screen space to allow for the Plugin Question. It should have a value of either: 0 - To indicate that Question Writer should allocate as much space as the largest option requires

1 - To indicate that Question Writer should allocate as much space as the first option requires

2 - To indicate that Question Writer should allocate enough space to display all the options

3 - To indicate that Question Writer should not allocate any space based on the option sizes

Second Parameter: (20) - This is the number of additional pixels in width that QW understands your component to require.

Third Parameter: (0) - This is the number of additional pixels in height that QW understands your component to require.

　

Identification

To make your component easy to use, you can change the dimensions of your flash file to 200x200 and add the following actionscript to the first frame in the main timeline to identify the symbol name, version and copyright information:

Note: It is best to make the check (this._parent==null), rather than (this==_root) as _root is replaced by Question Writer.

if(this._parent==null){ this.createTextField("version", 10, 0, 0, 200, 200); this.version.multiline = true; this.version.wordWrap = true; this.version.text = "Symbol: QWPQ-0-20-0-ComboBoxV1_7.swf\nVersion 1.0\nCopyright 2003-2010 Central Question Ltd."; }