Seppo - The Form Analysator

Step 1: Making the to CGI work

Make sure that your www server is able to run Perl CGI programs. Most of them are, but the configuration varies.

1. Copy the three files (seppo.cgi, form.pm and template.pm) to your CGI directory.
2. Make seppo.cgi readable and executable for the www server. Usually chmod 755 seppo.cgi will do the trick. Make sure that the www server is not able to modify the script - no write permissions for the file.
3. Check the global parameters by editing seppo.cgi. In unices you want to update the first line to point your Perl interpreter, while in Windows you do not probably have to touch the setting. The $CONFIG is used as a prefix for form definition files and output templates. $DATA is used with files that are written. If you are having trouble in introducing your favourite formula in form definition file because of filtered characters, you can edit $FORMULA_ALLOWED. However, do not forget that the more conservative the filtering is the more secure your system is.
4. Now you can test-drive your Seppo. Enter the url of the script to your browser (e.g. http://my-seppo-server/cgi-bin/seppo/seppo.cgi). The program should give you a response Error: Configuration file ./.form was not found. This means that you have not supply the form name in the variable formname, so Seppo can not know how to process your form.

Step 2: Set the questionnaire

The next step is to edit your questionnaire and make it available to your www server. Have a look at the comments in the example files (form-*.html) and you will do fine.

Currently Seppo can process only numeric input, so basically you can use only RADIO and CHECKBOX elements. Also TEXT fields can be used to acquire numeric data, like the year of birth. In CHECKBOX elements it makes sense to use only one option per question (on/off) as Seppo can not distinguish following set of options:

<b>1) What adjectives would you use to describe our company?</b><br>
<input type="checkbox" value="1" name="q1"> Good
<input type="checkbox" value="2" name="q1"> Very Good
<input type="checkbox" value="3" name="q1"> Excellent

Instead, you can embed several Seppo-questions to one form question:

<b>1) What adjectives would you use to describe our company?</b><br>
<input type="checkbox" value="1" name="q1"> Good
<input type="checkbox" value="1" name="q2"> Very Good
<input type="checkbox" value="1" name="q3"> Excellent

In analysis you can deal these items separately.

Important: Do not forget to set the formname variable in your form! It has to correspond with the rule and output template filenames (see steps 3 and 4).

Step 3: Program the rules for the analysis

After making the form you want to teach Seppo how to analyse it. Again, you might find the sample files (*.form) useful. Remember, that the first part of the file name has to correspond with the form's forname tags.

The order and the case of the keys is indifferent, and one (or more) spaces and/or tabs are used to distinguish the key field from the value. In response_ the two sets of values must be separated with ":s.

First, can set the name of your items (questions) with keyword item_name_X, where X corresponds the numbering in your HTML form (q1, q2, ...). The names can be used in output templates, but you can leave them undefined.

Example:

item_name_1 Item 1
item_name_2 Item 2
item_name_3 Item 3

Secondly, you define the index variables and their formulas. Index variables are useful if you want to count something out of single items, like an average or a number of correct answers. Actually, the formulas are interpreted and executed as a piece of Perl code and therefore all you can use all Perl operators and functions. You can't use other indexes in these formulas.

Important: There is a obvious security caveat here! As a server administrator you do not want to allow any of your clients or users to upload or edit the form files. They contain settings that are executed as a Perl code and adding a code that is being executed by the web server process is very easy. It is advisable to check once again that you are not running the web server with root / Administrator priviledges! Do not install Seppo if you do not know how to do this!

If desired, the index names can be left undefined.

Examples:

index_name_1 Sum of items
index_formula_1 q1+q2+q3

# Count an average of first two items (define no name for this index)
index_formula_2 (q1+q2)/2

# Random number between 1-10
index_formula_3 int(rand(10)+1)

Thirdly, you can set a set of response strings that can be used in your output template. You have an unlimited number of sets for the response. After counting the indexes Seppo goes through the set rules one at a time and sets the response string according to the first true condition statement.

In conditions, you are free to combine item values ( q1, q2, ...) and index values (i1, i2, ...).

Response sets can be used to obvious purposes like giving feedback according to the correct answers, but you can use them to set link or image URL:s according to the answers. This way Seppo can be "smartly" integrated to your existing www learning environment increasing its adaptability.

Examples:

response_1 "(i1 > 10)" "Index 1 is more than 10"
response_1 "(i1 < 10)" "Index 1 is less than 10"
response_1 "(i1 == 10)" "Index 1 equals with 10"

response_2 "(i1 > 10)" "http://myhost/welldone.html"
response_2 "(i1 <= 10)" "http://myhost/practice_more.html"

Seppo is able to save the form data - both raw and analysed data. save_data_raw makes Seppo append raw data to a file FORMNAME.raw in the data file. The save_data_analysed does the same (FORMNAME.txt), but you have to tell which fields you want to store:

• qN - Stores item N
• iN - Stores index N
• rN - Stores response N

Examples:

save_data_raw
save_data_analysed q1 q2 q3 i1

Note: You have to create the data files by hand, as Seppo wants you to make sure that you set the file permissions manually when creating the files.

Step 4: Edit the output template

Each form has one file that is used to produce the output after analysis. Again, the example files (tpl-*.html) should provide necessary information.

Congratulations!

Updated: 29-Oct-2002 / ML