Introduction
One of the design goals have been to make it as easy as possible to integrate new types of QuestionPages besides the already existing ones (cross, alternative and written). However as the QuestionPages are quite fundamental in the package one need to modify the source code of the applets and some of the cgi scripts, as well as make new ones. Below will follow a step by step description of which scripts and Java classes that are necessary to change and add.
Step 1, decide the data format.
A good idea before beginning with the QuestionPage is to decide the file format of how the QuestionPage data and the answers should be saved on the server. Currently the sub questions for a QuestionPage is saved in one file using this scheme (see the file syntax too):
QuestionText#AnswerText#rightAnswer#Variants of this format could be used if the new type needs more information for each question. As an example a QuestionPage type may have many correct answers for each subquestion. The correct answers may be stored at the rightAnswer position, but separated with a another delimiter than the "#". It would then look like this:
QuestionText#AnswerText#rightAnswerI@rightAnswerII@rightAnswerIII#
It is also a good idea to during this phase decide the name of the new type, e.g. myNewType. The name is used by the applets and the cgi scripts to now how the data of the QuestionPage should be parsed and handled.
Step 2, construct a QuestionPage
The second step is to construct a template QuestionPage with the graphical components needed for displaying the subquestions and the JavaScript functions needed for checking the student answers and sending the answers to the server. How the QuestionPage should look like is entirely up to the creator, the only requirements is that if the QuestionPage should be able to work in send mode it must be able to call the cgi script distans.perl in the appropiate manner. The parameters that should be sent to distance.perl: a, b, c, d and e must be sent in their correct format. Please refer to the QuestionPage chapter, or the source code examples for QuestionPages, for information concerning the format.
Step 3, create a make cgi script
After a prototype for a QuestionPage has been implemented, it is time to implement the cgi script that uses the information in a .data file to create the QuestionPage .html file on the server. For examples of already existing scripts of this kind, please see the source code for makeCross.perl, makeWritten.perl and makeAlt.perl. The code for these scripts may look a bit complicated, which is due to the fact that three languages are used. A perl program writes JavaScript code that in return writes HTML code. Don't worry to much about it, you will get used to it after a while. To make the code a little bit easier to generate, we have put the static parts (the parts that are independent of the text of the questions) in separate files in the JS/ directory. These files could then easily be merged (in Perl) to the end of the files that are generated. After step 3, you should have a Perl program that given a data file with the subquestions creates a new QuestionPage.
Step 4, modify the Java Applet code
Please read the chapter about the MakePage and ReadAnswer applets before reading this.
Graphical display
In order for the MakePageApplet to be able to display the new QuestionType so that a teacher can create and edit it, new Graphical classes have to be implemented for the MakePageApplet. It is advisable to start with the implementation of the subquestion panels (if they exist for the new type). There should be methods for setting and getting the texts/selections that makes out the new QuestionPage type. For details about these methods see the source code and the javadoc documentation for the AltPanel and CrossPanel.
After the subquestion panels have been successfully created you are ready to make the card Panels responsible of displaying one or more subquestion panels. This Panel must implement the ShowPanelInterface and should handle flipping between the subquestions and the storing of edited subquestions in the PageData object. Examples of classes of this Panel type are ThreeCrossPanels and TwoAltPanels.
Data structures
Each QuestionPage is stored in the applet using the PageData class. The answers of the student are stored in the AnswerData class. These two classes both have to be modified according to properties of the new QuestionPage type. The PageData has a variable named type which tells the type of the QuestionPage. The methods for PageData works in different ways depending on the setting of this variable. For example when the PageData is asked for the text corresponding to a certain answer this text would be the answer of one of the other subquestions, while for PageData objects of the type alt, the text will be one of the alternatives. The only way to deal with these differences is to modify the case statements that exists in many of the methods of PageData and AnswerData.
Communication Applet Server
Because the amount of data and how it is ordered, differs for the different QuestionPage types, the data retrieved from and stored on the server must be parsed distinct. All this is handled by the class DataLoader in the two methods getAllPageDataFromServer() and sendData(PageData). The first method retrieves the QuestionPages from the server and creates PageData objects for each of them. Depending on how the new QuestionPage data is stored, information may have to be parsed distinctly, this could be dealt with by changing the case statements found in getAllPageDataFromServer. The second method, sendData does the opposite; it takes information from a PageData object and parses it to strings that can be sent to the makeDataFile.perl script. This method must thus also be modified to handle the new QuestionPage type. For details see the source code for DataLoader and makeDataFile.perl
Core Applets
Due to the modularity between the modules, few changes are needed in
the core applets classes (MakePageApplet and ReadAnswerApplet).
However minor changes might be needed for specific features of the new
QuestionPage type. For example, the answers for cross pages in the MakePageApplet
could be randomly distributed by pressing the random button. As this feature
is impossible for the other types the button must be disabled for them.
This kind of behavior must thus be explicitly put into the code of
the methods of the applets.
Step 5, modify the getAllAnswers.perl script
The getAllAnswers.perl
script is called via the DataLoader by the ReadAnswerApplet
to load the students answers from the server. The data transfered
includes information about if the answers were correct or not (this of
course only applies to the answers that can be computer corrected). The
algorithms for checking the answers may differ between the QuestionPage
types and must thus be added in the getAllAnswer.perl script.