Last Update: February 3, 2001
Version 1.0


Copyright (c) 2001; Microburst Technologies, Inc.
All Rights Reserved.





UTEST PROGRAMMER'S GUIDE TECHNOLOGY SHARING AGREEMENT: Note that you may NOT resell nor redistribute any custom uTestTM Java, JavaScript, or CGI components without expressed written consent from Microburst Technologies, Inc.



Table Of Contents
1. Introduction Section 1
2. Creating Java Applets Section 2
   2.1 Setting Up Your Programming Environment Section 2.1
   2.2 answerQuestion() API Section 2.2
   2.3 Example Section 2.3
3. Additional Java Methods Section 3
4. Creating JavaScripts Section 4
   4.1 Setting Up Your Programming Environment Section 4.1
   4.2 answerQuestion() API Section 4.2
   4.3 Example Section 4.3
5. Additional JavaScript Functions Section 5
6. Customizing The uTestTM CGI Script Section 6
   6.1 Custom Data Recording Section 6.1
   6.2 Custom Data Analysis Section 6.2
   6.3 Custom "Thank You" Page Section 6.3
7. Additional Notes Section 7
8. Additional References and Resources Section 8






1. Introduction

What this programmer's guide does?

This programmer's guide is intended to describe how to use the uTestTM Application Program Interface (API) to create your own Java Applets and JavaScripts that can interface with the uTestTM Online Training System. It also documents all of uTest's public API's that may be useful while developing your own Java Applets and JavaScripts.

What this programmer's guide doesn't do?

This programmer's guide is not intended to be a introduction or tutorial into how to write Java Applets or JavaScripts. It will be assumed that the reader has some previous knowledge of Java and JavaScript programming.



2. Creating Java Applets
This section describes how to create your own custom Answer Applets that interface with uTestTM. This includes instructions on how to setup your development environment, a description of how to use the answerQuestion() API, and the complete source code for an example Answer Applet.


2.1 Setting Up Your Programming Environment

Java Compiler

The uTestTM applets and classes are written in Java 1.0 (for maximum browser compatibility), therefore you should begin by downloading the Java 1.0 Development Kit (JDK 1.0) from the Sun website.

The current version (which as of April 12, 2000 is JDK 1.0.2) can be downloaded from:

http://java.sun.com/products/jdk/1.0.2/

Linking To The uTestTM Class Files

In order to be able to compile any new Java applets that use the uTestTM API, the JDK compiler will need to be able to find the other uTestTM class files. The easiest way to do this is to copy all of the uTestTM class files into the same directory where you will be creating your Java source files.

As a test/example, try creating a new directory on your development computer. Copy ALL of the uTest class files into this new directory. Also, copy the "example.java" source file that was included with uTestTM into this directory. (You can find the "example.java" file - along with a test html page - in the "java" directory that was created when you installed/unzipped uTestTM on your computer). Try to compile the "example.java" file by typing: 

javac example.java
The "example.java" file should successfully compile without error. This is the same procedure that you will use to compile any new Java applets that you develop.


2.2 answerQuestion() API
The key to developing a Java Applet that will interface with uTestTM is the use of the uTestLibrary method answerQuestion(). That is, you can program any kind of logic or interface you want into your applets, providing that when you finally want to answer the question (by saving the value on the uTestTM answer sheet), your applet calls the answerQuestion() method. This section provides a detailed description of the answerQuestion() method and its parameters.

The answerQuestion() method is a static function of the uTestLibrary class and has the following prototype: 
public static synchronized int answerQuestion(String qNumber,
                                              String qType,
                                              String qPoints,
                                              String qClassification,
                                              String qAnswer)
Note that the method has 5 parameters, each of which is described in the table below:


  Parameter Name Description
1 qNumber A String representation of the question number to which the answer will be associated with. Valid values include any string representation of the integer question number, such as "1" or "2" or up to the max "200". (The question number).
2 qType The type of question being answered. Valid values include "multiple_choice", "true_false","short_answer","long_answer", or "essay". You may also abbreviate these types by the letters "m", "t", "s", "l", or "e", respectively.
3 qPoints A string representation of the number of points this question is worth, such as "1", "5" or "10". The default value is "1".
4 qClassification Any string used to indicate a classification for the question. Possible values include "HISTORY", "SCIENCE", or "BONUS". The default value is "NONE". Note that this parameter is not used at this time - so you may just set this parameter to "".
5 qAnswer Any string indicating the student's answer for this question. Typically you will get this value from the user's input and then just pass the value to this method.

Table 2.2.1 answerQuestion() API Parameters


The answerQuestion() method also has an int return value to indicate whether the answer was successfully set in the uTestTM answer sheet or not. If the answer was successfully set, then a value of 1 is returned. If the answer was successfully set, but had been previously set before, then a value of 2 is returned. Otherwise, if the answer was NOT successfully set, then a value of -1 is returned.

Note that this return value does not have anything to do with whether the answer is right or wrong... it simple indicates whether the answer was successfully saved or not on the uTestTM answer sheet.

See the example in the next section for an example call to the answerQuestion() method.


2.3 Example
The "example.java" file that is included with uTestTM contains the complete source code for an example Answer Applet. You can find this "example.java" file - along with a test html page - in the "java" directory that was created when you installed/unzipped uTestTM on your computer. Take a look at the source code of this Java 1.0 applet. Note how the action event handler is setup to call the answerProduct() API: 
if (uTestLibrary.answerQuestion(qNumber,
                                "T",
                                qPoints,
                                qClassification,
                                uTestInternational.valueTrue) > 0)
{
   // The answer was successfully set.
}
else
{
   // The answer was NOT successfully set.
}

Feel free to modify this example or use it as a model to create your own custom applets.

Note that throughout the example, you will see calls to various other uTestLibrary methods. Those methods, and others, have been documented in the next section and may be useful when developing your own custom applets.


3. Additional Java Methods
This section lists some of the other public methods contained in the uTestLibrary class and which may be useful when developing your own custom Java applets.

1. atof()

Method to convert a string to a floating point value.

Prototype: float atof(String pString);
Class: uTestLibrary
@param pString - The string to be converted.
@return Returns the float representation of the string.


2. atoi()

Method to convert a string to an integer value.

Prototype: int atoi(String pString);
Class: uTestLibrary
@param pString - The string to be converted.
@return Returns the int representation of the string.


3. clearAllAnswers()

Method to clear all answers and reset the text clock/counters.

Prototype: boolean clearAllAnswers();
Class: uTestLibrary
@return Always returns true.


4. clearAnswer()

Method to clear the current answer of a specified question number.

Prototype: boolean clearAnswer(int numberToClear);
Class: uTestLibrary
@param numberToClear - A string representation of the question number to clear.
@return Returns true if the answer was cleared. Otherwise, returns false.


5. compareStrings()

Method to compare two strings (without case-sensitivity).

Prototype: boolean compareStrings(String s1,String s2);
Class: uTestLibrary
@param s1 - The first string to compare.
@param s2 - The second string to compare.
@return Returns true if the strings are equal.


6. createCheckboxArray()

Method to parse a specified comma-delimited string and create an array of checkboxes.

Prototype: Checkbox[] createCheckboxArray(String pString,CheckboxGroup cbg);
Class: uTestLibrary
@param pString - The string containing the comma-delimited items that are to be separated into the checkbox array.
@param cbg - The checkbox group for the checkboxes in the array. (use null if multiple selections are allowed)
@return Returns the array of Checkboxes.


7. createChoiceItems()

Method to parse a specified comma-delimited string and add each item to a new Choice object.

Prototype: Choice createChoiceItems(String pString);
Class: uTestLibrary
@param pString - The string containing the comma-delimited items that are to be added to the Choice object.
@return Returns a new Choice object with the specified items added.


8. getAnswer()

Method to get the current answer of a specified question number.

Prototype: String getAnswer(String qNumber);
Class: uTestLibrary
@param qNumber - A string representation of the question number.
@return Returns a string containing the current answer for that question number.


9. getColor()

Method to get a Color object based on a text string.

Prototype: Color getColor(String colorString);
Class: uTestLibrary
@param colorString - A string containing a color name or rgb value.
@return Returns a new Color object with the specified color.


10. getElement()

Method to search a specified delimited string and return the Nth element.

Prototype: String getElement(String src, int n, char delimiter);
Class: uTestLibrary
@param src - The string to search.
@param n - The Nth element in the string (beginning at 0).
@param delimiter - The delimiter character by which to separate the string.
@return Returns the Nth element as a string or returns null if the element at the specified index does not exist.


11. gotoUrl()

Method to go to (i.e., link) a specified page.

Prototype: void gotoUrl(Applet parent,String nextPage,String target);
Class: uTestLibrary
@param parent - A reference to the parent applet that called this method.
@param nextPage - The page to go to.
@param target - The target frame for the new page.


12. padString()

Method to pad a string with spaces such that the String length is as specified. Note: If the string length is greater than the specified length, the string is truncated.

Prototype: String padString(String pString,int length);
Class: uTestLibrary
@param pString - The string to be padded/truncated.
@param length - The length to make the padded string.
@return Returns the new String of the desired size.


13. readFile()

Method to read a file.

Prototype: String readFile(Applet parent,String file);
Class: uTestLibrary
@param parent - A reference to the parent applet that is reading the file.
@param file - The file to read.
@return Returns a String containing contents of the file.


14. replace()

Method to replace all occurrences of a specified string with a new string. The search is not case-sensitive.

Prototype: String replace(String src, String rstring, String nstring);
Class: uTestLibrary
@param src - The source string to be searched.
@param rstring - The string to be replaced in src.
@param nstring - The new string to replace the rstring.
@return Returns the modified src string.


15. replaceSection()

Method to replace the first occurrence of a section containing a specified start string, ending with a specified end string, and containing a specified middle string with a new string. The search is not case-sensitive.

Prototype: String replaceSection(String src, String startString, String endString, String middleString, String nstring);
Class: uTestLibrary
@param src - The source string to be searched.
@param startString - The start string of the section.
@param endString - The end string of the section.
@param middleString - The middle string of the section.
@param nstring - The new string to replace the section.
@return Returns the modified src string.


16. stripLetters()

Method to strip all non-numeric characters from a specified String.

Prototype: String stripLetters(String pString);
Class: uTestLibrary
@param pString - The string to have the letters stripped.
@return Returns a new String with no non-numeric characters.



4. Creating JavaScripts
This section describes how to create your own custom JavaScripts that interface with uTestTM. This includes instructions on how to setup your development environment, a description of how to use the answerQuestion() JavaScript API, and the source code for an example JavaScript.


4.1 Setting Up Your Programming Environment
Since the source code of JavaScripts is added as part of the HTML on web pages, no compiler is needed to compile JavaScripts. To use JavaScripts with uTestTM, however, you will need the uTestTM class files. In particular, JavaScripts must use the uTest JavaScript Interface Applet as the means by which to call uTest's Java foundation classes.

The uTest JavaScript Interface Applet

In order for JavaScripts to be able to call a uTestTM Java method, they must go through a special JavaScript Interface Applet. This special applet is called "uTestJSI" and must be added to each HTML page that has a JavaScript on it that interface's with uTestTM. You only need one instance of the "uTestJSI" applet on each page that uses a JavaScript....and usually the applet is hidden near the bottom of the HTML page. The syntax for adding the "uTestJSI" applet to your page is similar to adding any other Java Applet to your page. An example is shown below: 

<APPLET CODE="uTestJSI.class" CODEBASE="../classes/" NAME="uTestJSI" WIDTH="2" HEIGHT="2">
</APPLET>
By doing this, JavaScripts can access the uTestJSI methods by using the syntax: 
document.uTestJSI.METHODNAME
...where METHODNAME is the name of the method you want to call. See the next two sections for more information.


4.2 answerQuestion() API
Similar to developing Java Applets to interface with uTestTM, the key to developing a JavaScript that will interface with uTestTM is the use of the answerQuestion() API. That is, you can program any kind of logic or interface you want into your JavaScripts, providing that when you finally want to set an answer on the uTestTM answer sheet, your JavaScript calls the answerQuestion() method. This section provides a detailed description of the answerQuestion() method and it's parameters.

The answerQuestion() method used by JavaScripts is a public method of the uTestJSI class and has the following prototype: 
public int answerQuestion(String qNumber,
                          String qType,
                          String qPoints,
                          String qClassification,
                          String qAnswer)
Note that the method has 5 String parameters, each of which is described in the table below:


  Parameter Name Description
1 qNumber A String representation of the question number to which the answer will be associated with. Valid values include any string representation of the integer question number, such as "1" or "2" or up to the max "200". (The question number).
2 qType The type of question being answered. Valid values include "multiple_choice", "true_false","short_answer","long_answer", or "essay". You may also abbreviate these types by the letters "m", "t", "s", "l", or "e", respectively.
3 qPoints A string representation of the number of points this question is worth, such as "1", "5" or "10". The default value is "1".
4 qClassification Any string used to indicate a classification for the question. Possible values include "HISTORY", "SCIENCE", or "BONUS". The default value is "NONE". Note that this parameter is not used at this time - so you may just set this parameter to "".
5 qAnswer Any string indicating the student's answer for this question. Typically you will get this value from the user's input and then just pass the value to this method.

Table 4.2.1 answerQuestion() JavaScript API Parameters


The answerQuestion() method also has an int return value to indicate whether the answer was successfully set in the uTestTM answer sheet or not. If the answer was successfully set, then a value of 1 is returned. If the answer was successfully set, but had been previously set before, then a value of 2 is returned. Otherwise, if the answer was NOT successfully set, then a value of -1 is returned.

Note that this return value does not have anything to do with whether the answer is right or wrong... it simple indicates whether the answer was successfully saved or not on the uTestTM answer sheet.

See the example in the next section for an example call to the answerQuestion() method.


4.3 Example
The "example_javascript.html" file that is included with uTestTM contains the complete source code for an example JavaScript. You can find this "example_javascript.html" file in the "javascripts" directory that was created when you installed/unzipped uTestTM on your computer. Take a look at the source code of this example and notice how the answerQuestion() API is initiated via "onClick" events. The actual call looks like this: 
document.uTestJSI.answerQuestion("20",               <!-- Question Number -->
                                 "MULTIPLE_CHOICE",  <!-- Question Type -->
                                 "5",                <!-- Question Points -->
                                 "NONE",             <!-- Question Classification -->
                                 answer);            <!-- Selected Answer -->

Feel free to modify the example or use is as a model to create your own custom JavaScripts.


5. Additional JavaScript Functions
This section lists some of the additional methods contained in the uTestJSI class and which may be useful when developing your own custom JavaScripts.

1. clearAnswer()

Method to clear the current answer of a specified question.

Prototype: boolean clearAnswer(String qNumber);
Class: uTestJSI
@param qNumber - The question number for which the answer is to cleared.
@return Returns true if the answer was cleared. Otherwise, returns false.


2. clearAnswers()

Method to clear all answers and reset the test clock/counters.

Prototype: boolean clearAnswers();
Class: uTestJSI
@return The method always returns true.


3. getAnswer()

Method to get the current answer of a specified question.

Prototype: String getAnswer(String qNumber);
Class: uTestJSI
@param qNumber - The question number for which the answer is to be returned.
@return Returns a string containing the current answer for the specified question.


4. getNumAnswered()

Method to get the current number of questions that have been answered.

Prototype: int getNumAnswered();
Class: uTestJSI
@return Returns a current number of questions that have been answered.


5. getTestTime()

Method to get the current number of milliseconds that have elapsed since the test began.

Prototype: long getTestTime()
Class: uTestJSI
@return Returns the test time in milliseconds.


6. getUpdateFlag()

Method to get the current value of the update counter. The update counter automatically gets incremented each time a question is answered or cleared. (This can be useful if monitoring for changes to the answer sheet).

Prototype: int getUpdateFlag()
Class: uTestJSI
@return Returns the current value of the update counter.


6. Customizing The uTestTM CGI Script
This section provides some tips and pointers for modifying the utest.pl Perl CGI script to 1) customize the data recording format, 2) customize the data analysis subroutine (for grading purposes) and 3) customize the final "thank you" page that is displayed to the user.

Note that it will be assumed that the reader already has some previous knowledge of Perl/CGI programming.


6.1 Custom Data Recording
Currently all data recording in the uTest CGI script is handled by the "write_answer_sheet" subroutine. Any modifications done to this subroutine should also be reflected in the "read_answer_sheet" subroutine.


6.2 Custom Data Analysis
Currently all data analysis in the uTest CGI script is handled by the "process_answers" subroutine. You should be able to trace through that subroutine and see where you can add any additional analysis subroutines that you need.


6.3 Custom "Thank You" Page
Currently the "create_thankyou_page" subroutine of the uTest CGI script handles generating the HTML for the "Thank You" page. You should be able to recognize the HTML in that subroutine and see how it can be modified for your needs.


7. Additional Notes
This section contains some additional notes that may be helpful when developing your own Java Applets and Java Scripts.

  • Don't Forget To Test! It is essential that you test any new applets or JavaScripts that you create. Test them with different browsers....and if possible, on different operating systems. This is because there are slight differences in the way different browsers and different operating systems run and display Java applets. So the more testing you can do, the better.


    8. Additional References and Resources
    Listed below are some books and URLs where you can find additional information about Java and JavaScript programming: