ReadMe.txt -- PerlTest Version 1.0

There are 4 files that are needed  to make this script run;

test.htm

This is the html file that contains the form for the actual test.  The number of questions has no impact.  Keep in mind that the order of the questions on this page determines the order they are checked by the program.  The order of the questions on this page must  be the same as the order of their corresponding answers in the 'answers.txt' file.  It doesn't matter what the 'Name' of the question is, but the 'Value' of the question must be identical to the answer listed in the 'answers.txt' file. If the identity_factor in 'test.cgi' is set to1, then the identity field must be the first field on this page, before any of the questions.  The example 'test.htm' provided may provide a clearer picture of the actual rules of engagement.  Besides the questions, the only thing to be changed on this file is the 'Action' parameter in the 'Form' line to point to the location of the 'test.cgi' script on your server.

testlog.htm

This is the html file that is updated with test results as they come in.  It is also used by the Perl script to count the total average score and number of people tested. The example one provided should serve any purpose to start with, however, the basic layout of the page (color, font, etc.) can be adjusted by changing the html in this file.  Don't change the <!-- lines or their locations, they are important to the positioning of the log info.  Also, don't move the "Score =" part right under the <!--score--> line because this is used to count the total average and number of people tested.  If you're running on a Unix server, make sure to set the permissions on this file to be readable and writeable by everyone involved.

graphlog.htm

This is the html file that draws the graph comparing correct and incorrect answers for each question.  Make sure to put this file in the same directory as the two graphic files "redbar.jpg" and "bluebar.jpg".  If you're running on a Unix server, make sure to set the permissions on this file to be readable and writeable by everyone involved.

bluebar.jpg and redbar.jpg

These are the two graphic files that are used to draw the bars on the graphlog page.  Put these two files in the same directory as the graphlog.htm file.

answers.txt

This is the file that will contain the test answers.  The answers should be listed one per line.  Make sure that the last answer in the list has a carriage return after it, or it won't be counted properly.  The answers should correspond identically to the 'Values' returned by your test form, and should be in the same order as the questions are listed on the test form.

test.cgi

This is the main Perl script and should be placed in the cgi-bin on your server.  There are only a few things that have to be changed on it:

$answerFile : The server location of the 'answer.txt' file.
$logFile : The server location of the 'testlog.htm' file.
$logFileUrl : The URL of the 'testlog.htm' file.
$graphFile: The server location of the 'graphlog.htm' file.
$graphFileUrl: The URL of the 'graphlog.htm' file.
$testUrl : The URL of the 'test.htm' file.

$identity_factor : This variable should be set to either 1 or 0.  If you're requiring the user put in their identity while doing the test then set it to 1.  Otherwise set it to 0.  If it's set to 1, you MUST have the first form value equal the users identity (email, name, code, etc., it doesn't matter).  If you set it to 0, you MUST NOT include an identity field on your form.

Some other things to keep in mind:

- The 'display_results' subroutine may be personalized as you want.  Currently, I've got it providing a link back to the test and also to the 'testlog.htm' and 'graphlog' files.  You may want to hide these files  from the user, or not allow repeat tests, so these links can be taken out.  Also, the color, font, etc. of the results screen can be adjusted within this subroutine simply by changing the HTML.