Master Quiz V2 Manual

To install and use Master Quiz V2, your domain server must be Unix or Linux, have sendmail or qmail available, and have Perl version 5+ installed.

Use an FTP program to install Master Quiz V2. CuteFTP and WS_FTP for Windows and Transmit for Macintosh are among the many FTP programs that can be used to change directory and file permissions. Many FTP programs are listed at http://tucows.com/

List of Files

Here is a list of the files you should have received when you generated Master Quiz V2.

If you did not receive all of the above files, please write to us at programmer@willmaster.com — include a list of the files you did receive and the domain name Master Quiz V2 was generated for.

Getting Started

The three program files must be installed into a directory that is allowed to run Perl CGI programs.

You may wish to make a subdirectory in your cgi-bin within which to install Master Quiz V2. Installing it in its own directory can provide a better sense of organization when you have or anticipate having other programs in your cgi-bin.

To install Master Quiz V2, upload the three program files into the directory you decided upon, whether the cgi-bin itself or a subdirectory.

Setting Permissions

This is an information section only, for use if you unsure about setting program or directory permissions.

Some servers require 755 permissions for directories that will write files or for the files themselves. Others, 766 or 777.

If a script creates its own directories and files, don't change the permissions unless you know what you're doing. (In other words, if it works like it should then don't fix it.)

755

Global read/execute permission
(For scripts, directories and data files. If your server won't write to directories and files with 755, use 766):

Owner —		read-write-execute
Group —		read-execute
World —		read-execute

766

Global read/write permission
(If your server won't write to directories and data files with 755 or 766, use 777):

Owner —		read-write-execute
Group —		read-write
World —		read-write

777

Global read/write/execute permission
(For directories and data files, try 755 first, then 766, and 777 last):

Owner —		read-write-execute
Group —		read-write-execute
World —		read-write-execute

Some FTP programs use the term "Other" or "Global" instead of the term "World" as used above.

The Control Panel

If you installed mq.cgi into a directory named mq, then the URL might be something like this:

The first time you access your control panel, you will be asked to provide a password. What you type here will be your password for future access to the control panel.

Once access is granted, the fact is stored in a cookie on your browser until either one of these happens:

When either of the above happens, the cookie is removed from your browser. (Cookies must be turned on to use the control panel.)

On the "Program Configuration" page, specify basic information Master Quiz V2 needs to operate. Save the information.

Now, you'll see the control panel Index Page. Here, you create/modify/delete quizzes, change program configuration or password, if necessary, and log off when you're done with the control panel.

Creating a Quiz

Here, you can create a new quiz in its entirety or, if one or more quizzes are already in the database, you have the option of selecting a quiz from a dropdown list to use as a base for the new quiz.

Each quiz uses four pages of information in the database to generate the quiz and process quiz submissions.

Page 1:

Foundation. This is where the quiz's general configuration is specified.

The quiz's name —

Type a name for this quiz for your convenience. This name is used only in the control panel.

Cookies —

With the use of a cookie in the quiz taker's browser, the quiz taker may be restricted to doing the quiz only once for a certain period of time. If a name and/or an email address is provided on the quiz form, the information will be used to apply the cookie only to that individual. Otherwise, the cookie will apply to all who use that browser.

To have this:	Put this in the "cookie" form field:
No restriction	Leave the form field blank.
Apply restriction only until the browser is exited.	Put a 0 (zero) in the form field.
Apply the restriction for one or more days.	In the form field, type the number of days you want the cookie to exist in the browser — maximum 3652 days (10 years)

The quiz taker's name —

Specify whether or not you want the form to contain a field for the quiz taker's name. If "yes," also specify whether or not the name must be provided in order to submit the quiz.

The quiz taker's email address —

Specify whether or not you want the form to contain a field for the quiz taker's email address. If "yes," also specify whether or not the email address must be provided in order to submit the quiz.

Custom fields —

You may specify custom fields in addition to the built-in name and email address. Fields may not begin with the letter "Q" and they may contain only alphanumeric characters.

Custom fields may be required to be filled in before submitting the quiz or they may be optional.

In the textarea field, specify whether or not the field is required followed by a space followed by the field name — one such set per line. Example:

Yes Department
No BossName

The information the quiz taker provides in the custom fields can be put into database, email, and/or the results page. See Placeholders for Emails and Results Page for more information.

Submit button text —

Specify the text for the quiz submit button.

Page 2:

Questions and Answers. The quiz questions and answers are specified here. Each answer is marked as correct, incorrect and/or given point values for scoring.

Questions, answers, selection methods —

The page has three blank question/answer/selection method areas. If you need more than that, fill in the first three and click the "More Questions" button.

Whenever this control panel page is loaded into your browser, it will display all of the questions previously saved plus three blank areas.

For each question/answer/selection method area:

Type the quiz question in the place provided.
Each answer must be marked as being a right answer, a wrong answer, or given a point value for scoring.

There are two types of marks:
1. Right/Wrong
2. Numerical score value
All answers in a quiz should be one or the other, either right/wrong or have numerical score values.

Type the answers in the place provided — the mark, a space, and the answer on a line by itself. Blank lines between the sets are allowed.

Here is an example of three answers with right/wrong marks:
```
Right The sky is blue.
Wrong The sky is falling.
Wrong The sky is solid.
```
Here is an example of three answers with numerical score value marks (the score value may be a negative number):
```
100 The sky is blue.
50 The sky is falling.
-10 The sky is solid.
```
Specify the selection method.
- Radio buttons allow the quiz taker to select no more than one answer.
- Checkboxes allow the quiz taker to select any, all, or none of the answers.
- A dropdown list allows the quiz taker to select no more than one answer.
- A select box allows the quiz taker to select any, all, or none of the answers.

Page 3:

Disposition. This page is where you specify what happens when the quiz is used. It's a long page because there are so many options:

The only fields that must be filled in is the URL of a default results page. Everything else on this page is optional.

The control panel page itself has detailed instructions.

Results Page — The results page is the page the quiz taker sees after s/he has taken the quiz and clicked the submit button.

The results page doesn't actually have to contain scores. It could be a "thank you" page, with or without scores, or the subsequent page of a multi-page quiz, with or without presenting scores so far.

The location of several results pages may be specified here, the score of the quiz to determine which results page to display.

Results pages are templates that may contain placeholders for information collected on the form and for quiz results. See Placeholders for Emails and Results Page for information about using placeholders in the results page.
Emails — Optionally, up to three emails may be sent whenever a quiz is submitted. As examples, an email might be sent to yourself, one to the quiz taker, and another to an autoresponder or list server.

See Placeholders for Emails and Results Page for information about using placeholders in the emails.
Results Display — In this section, you can specify what information to include in the quiz results when printed in the emails and on the results page. You can also specify the formatting when printed on the results page.

The information you specify here will be printed in the emails and/or on the results page wherever the [[RESULTS]] placeholder is found. Other placeholders can be used (see Placeholders for Emails and Results Page). The information specified in this section applies only to the [[RESULTS]] placeholder.
Databases — Optionally, up to three databases may be updated whenever a quiz is submitted. As examples, one database might be for yourself and another for a client. Or, you may wish one database to contain different information or be formatted differently than another.

The databases may be formatted with tab-delimited fields (TSV, tab separated values) or with comma-delimited fields (CSV, comma separated values). These files can then be downloaded from the server and imported into popular office computer spreadsheet and database programs.

Page 4:

Form Generation. Optionally, you may specify formatting for the questions and answers on this page before clicking the button to generation the HTML form for the quiz.

See Customizing the Generated Form if you wish to make formatting changes to the form after it's been generated.

Customizing the Generated Form

You can change the generated HTML form as you wish, so long as these items are not changed:

Other than that, you may do as you please — change fonts, colors, table widths and backgrounds, email and name form field sizes, and so forth. Just be sure to test the form after changing it, before taking it live.

If you want to remove the form submit button and replace it with an image to click for form submission, you may do so. This is the only exception where an entire tag may be removed and replaced. Example of replacement:

Modifying a Quiz

Some quiz information can be modified without having to re-generate the quiz form. Use this table as a guide:

Item that changes Quiz form
re-generation
required?
The quiz's name No
Cookie specification No
The quiz taker's name requirements Yes
The quiz taker's email address requirements Yes
Custom fields changes Yes
Submit button text Yes
Questions, answers, selection methods Yes
Results page templates or locations, including changes in branching depending on score No
Email template changes No
Results formatting for emails or results pages No
Database changes No
Quiz formatting changes on the generation form itself Yes

Deleting a Quiz

You will then need to select the quiz you want to delete in two separate dropdown lists. Once the same quiz is selected in both dropdown lists, clicking the submit button will delete the quiz. No additional verification is required.

Multi-Page Quizzes

Multi-page quizzes are quizzes presented on individual pages, in a certain sequence.

The results page of the first quiz contains the second quiz. The results page of the second quiz contains the third quiz. And so forth.

Optionally, the scores of previous quiz pages in the series may be incorporated into the scores of current quiz page.

As an example, in a three-page quiz, the second quiz may depend on the scores of the first. If a strong aptitude for beekeeping is found, as determined by the score of the first page (still as an example), the second quiz page may be different than if the aptitude was not found. It may be illustrated this way:

The multi-page quiz sequence can be anything needed for your implementation, from a straight sequence to a convoluted branching with different "thank you" results pages.

Placeholders for Emails and Results Page

Emails and results pages may contain information gathered from the quiz along with quiz results. Emails are specified in the control panel. The locations of results page template files are also specified in the control panel.

The following placeholders may be used in emails and in results page template files:

This placeholder:	Is replaced with:	Can be used for quizzes with
This placeholder:	Is replaced with:	right/wrong answers?	numerical score valued answers?
[[QName]]	The quiz taker's name, provided it was supplied on the quiz form.	Yes	Yes
[[QEmail]]	The quiz taker's email address, provided it was supplied on the quiz form.	Yes	Yes
[[_________]]	The information provided on the form in custom fields. Replace the underscore with the field name.	Yes	Yes
[[NUMBER_OF_QUESTIONS]]	The number of questions on the current quiz page.	Yes	Yes
[[TOTAL_NUMBER_OF_QUESTIONS]]	The total number of questions on all quiz pages taken so far*	Yes	Yes
[[NUMBER_OF_ANSWERS]]	The number of answers on the current quiz page.	Yes	Yes
[[TOTAL_NUMBER_OF_ANSWERS]]	The total number of answers on all quiz pages taken so far*	Yes	Yes
[[NUMBER_POSSIBLE_RIGHT]]	The number of right answers to choose from on the current quiz page.	Yes	No
[[TOTAL_NUMBER_POSSIBLE_RIGHT]]	The total number of right answers to choose from on all quiz pages taken so far*	Yes	No
[[NUMBER_POSSIBLE_WRONG]]	The number of wrong answers to choose from on the current quiz page.	Yes	No
[[TOTAL_NUMBER_POSSIBLE_WRONG]]	The total number of wrong answers to choose from on all quiz pages taken so far*	Yes	No
[[HIGHEST_POSSIBLE_SCORE]]	The highest possible score of the current quiz page.	No	Yes
[[TOTAL_HIGHEST_POSSIBLE_SCORE]]	The highest possible score of n all quiz pages taken so far*	No	Yes
[[LOWEST_POSSIBLE_SCORE]]	The lowest possible score of the current quiz page.	No	Yes
[[TOTAL_LOWEST_POSSIBLE_SCORE]]	The lowest possible score of n all quiz pages taken so far*	No	Yes
[[NUMBER_SELECTED_RIGHT]]	The number of right answers that were selected on the current quiz page.	Yes	No
[[TOTAL_NUMBER_SELECTED_RIGHT]]	The number of right answers that were selected on all quiz pages taken so far*	Yes	No
[[NUMBER_SELECTED_WRONG]]	The number of wrong answers that were selected on the current quiz page.	Yes	No
[[TOTAL_NUMBER_SELECTED_WRONG]]	The number of wrong answers that were selected on all quiz pages taken so far*	Yes	No
[[QUIZ_PERCENTAGE_SCORE]]	The number of right answers that were selected on the current quiz page divided by the total number of right answers available for selection, expressed as a percentage. The percentage is rounded to the nearest whole number.	Yes	No
[[QUIZ_PERCENTAGE_SCORE.0000]]	The quiz percentage is rounded to the nearest four decimal places. The number of zeros following the period in the placeholder determines the number of decimal places the percentage is rounded to.	Yes	No
[[TOTAL_QUIZ_PERCENTAGE_SCORE]]	The number of right answers that were selected on all quiz pages taken so far* divided by the total number of right answers available for selection, expressed as a percentage. The percentage is rounded to the nearest whole number.	Yes	No
[[TOTAL_QUIZ_PERCENTAGE_SCORE.00]]	The quiz percentage is rounded to the nearest two decimal places. The number of zeros following the period in the placeholder determines the number of decimal places the percentage is rounded to.	Yes	No
[[QUIZ_SELECTED_SCORE]]	The total of the numerical score values of answers that were selected on the current quiz page.	No	Yes
[[TOTAL_QUIZ_SELECTED_SCORE]]	The total of the numerical score values of answers that were selected on all quiz pages taken so far*	No	Yes
[[RESULTS]]	The results of the quiz. What prints here is determined on your specifications on the "Page 3 of 4, Disposition" control panel page.	Yes	Yes

(of a multi-page quiz), provided the scores from the previous pages are combined with the scores of the current quiz. (See control panel "Page 3 of 4, Disposition — Results Page — 1a.)

Master Quiz V2

M A N U A L

Requirements