The following steps are required to install the wquiz.cfg program.

These are the installation instructions for the development version of the 
software.. These provide a temporary method for installing the program until a 
fully featured installation script / process can be written.


Pre-Requisites
--------------
The software is designed and tested for use on a Linux Apache web server with
a MySQL database for the questions.
It may work on other operating systems and servers, but I am unable to give
any advice on problems experienced other than on Linux, Apache and MySQL.



Step 1 - Untar the files
------------------------
Untar the archive into your preferred directory.
This directory must allow the perl executables to be run.

This will typically be enabled in Apache using entries similar to the following:

        ScriptAlias /cgi-bin/ /var/www/cgi-bin/
        <Directory "/var/www/cgi-bin">
                AllowOverride all
                Options ExecCGI -MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        </Directory>
		
Or if you include it in a .htaccess file then 
Options ExecCGI - MutlViews

generally this should already be setup by default, you just need to make sure
it goes into your cgi-bin directory.

The zip file will create the directory quiz. 
WARNING: you should make sure that there is no other program 
using the quiz directory, otherwise you may end up with conflicting files.

You can untar the file to a different directory first, and then rename the 
directory to any suitable name.

To untar in the current directory (creating the quiz subdirectory) then use
tar -xvzf wquiz-0.3.2.tgz


If you are using a hosted web site then you can extract the files to your local 
machine (the .zip version is made available for windows users), and extract the 
files into folders on you local machine ready to ftp them to the web server. If 
you are transfering them from a different system then you need to pay particular
attention to the file permissions (see later)


Step 2 - Copy the sample files
------------------------------
The sample files are all contained in a seperate directory, so that
if you are upgrading from an older version the customizations will not be lost.
If installing this as a first install then you should copy the quiz.cfg and the
template files 
into the main directory.

Note: If you have customized your admin templates then the customizations may be
lost during an upgrade. It is recommended that a backup is taken of any 
customized template files and that they are restored after the upgrade.

The files can be installed by performing the following commands from
inside the wquiz directory:

cp -r samples/* .

If you are preparing this on a local computer ready to transfer the files
to a web server then copy the entire samples directory into the quiz directory.


You should also create a directory in your normal web server html area 
(not the ScriptAlias directory), which should hold the template images (these 
can be customised later).

This should be created as /wquiz. If you use a different directory then you will
need to manually update all the template html files.

e.g. if your documentroot is /var/www/html
cp -r wquiz /var/www/html

or copy the directory to your wquiz /public_html directory when uploading 


Step 3 - Customise the config file
----------------------------------
Open the file quiz/quiz.cfg in your favourite text editor.

The following entries need to be changed, other changes are optional
depending upon your system and preferences. Be careful when editing the file
to ensure that the syntax is kept the same. This is a perl format file
so it needs a semi-colon ';' at the end of each line. All lines begining with a 
hash character are comments.

$dbname
This should be correct for most systems using the mysql database. 
If you want to use a different database name to "quiz" then change that
part of the string. e.g. if you want your database to be "myquiz" change the 
entry to: $dbname="DBI:mysql:myquiz:localhost";
Or some hosting companies may include your username in the database name, so you
may have to use username_quiz in that part of the dbname field.

If you are using a different server name then change the localhost value to the
IP address of the server (and if not using the default mysql port number append
with :portnumber). You can change the database type by replacing mysql with an 
alternative perl database engine type, but if so the install script may not 
work.

$dbuser
Set this to the username with access to the database. If you want to let the
install script create the database for you then this will need sufficient 
permission to create a new database (which can be changed to a user with lower 
privilege later if required). If not then it will need update access to the 
tables. This needs to be created in the database before proceeding with the 
install.

$dbpass
The password to go with the above username

$dbtable
This is the name of the table used to hold the questions. This should
be unique to each install
$dbsessiontable
This should be the same as $dbtable followed by _session
$dbactivetable
This should be the same as $dbtable followed by _active
$dbsettingsnumtable
This should be the same as $dbtable followed by _settings_num


$adminuser
The username to logon to administer the quizzes with. This is not
configured anywhere else

$adminpass
The password for the above user. It is very important that this is changed
as the default password is available to anyone.

Log Files
The log files need to be set to a directory that the server has write 
permission to. This should be a directory which is not available to the public, 
or that has access restrictions placed on it

Administrator Details
These details are needed for the email notification of errors.
Please enter the details of your mail gateway and addresses. 
SMTP User authentication is not currently supported.
Email notification can be disabled by setting $emailerror to 0.

ActiveSecurity
If you would like to enable the Anti-DOS (Denial of Service) protection
then enable this by setting $activesecstatus to 1, and updating the files
with a directory which it has read and write access to.

Header and Footer files
These can be set to files that you want embedding in the header and footer
of each page. See the full adminstrator guide for details of how these should
be used.

Formatting Options
There is no need to make any changes to the formatting options at this point.
See the full documentation for details of how these can be changed.


QuizSpecific Section
The following entries should be tailored to your individual quiz

@category
a comma seperated list of all the quiz names. "all" is a special case
and will allow questions to be taken from all sections. Ensure that quotes
are put around all the entries.

@allowedcategory
Set to the same as @category

The formatting of the following sections are important. These must be written as
"quizname" => "Text String" where the quizname matches the categories already defined.
They can be split across multiple lines by having a line feed after the separating 
commas.

%quiznames
A long title for the quiz

%numquestions
The number of questions per test. This must be smaller than the number of questions
in the quiz.

%quizintro
A text or html string describing the quiz


Step 4 - Permissions
--------------------
If the tar file has been installed directly on to the system then
the file permissions should be correct. If you are ftp'ing the files to
a different computer then you should check that the permissions of all the files
ending .pl are set with execute permission (e.g. 775).
This applies to the files in the top directory, and to those in the admin 
directory.


Step 5 (optional) - Create the database
---------------------------------------
If you are using a hosted server you may need to create the database manually. If
so create the directory and user first. If you have full admin rights to the 
mysql database then this will be created by the following step.


Step 6 - Run the install script
-------------------------------
You should now run the script /cgi-bin/quiz/install.pl ,which can be called
from your web browser. The script which will create the database with the 
basic information needed to get started.

The script will first check to see if the database exists, and if it does not it
will attempt to create it. If the tables already exist then it will not proceed 
(unable to reinstall using the script), otherwise it will create empty tables for
all of the required tables.

If you are unable to run the script, or the install fails then details of how to
manually setup the database are included in the administrator guide.

You can delete the index.pl script (or set it's permissions to non-executable), 
although the script will fail if run again, it may give away some additional
information.


Step 7 - Enable Offline Mode if req'd
-------------------------------------
If you want to allow offline mode then as well as enabling the offline quiz using 
offlinequiz value, you need to create the file specified by offlinecountfile 
setting, and set it with a numerical value. This is by default /var/quiz/offline.qcf
This can be done on a *NIX system by:
mkdir /var/quiz
chown <apacheusername> /var/quiz
echo 1 > /var/quiz/offline.qcf
chown <apacheusername> /var/quiz/offline.qcf

(replacing <apacheusername> with the username that the apache server runs under.
This is typically http, www, apache, nobody or www-data depending on your sytem.
You may also need to update the templates, or your site links to point at the 
offline.pl file.

If you do not want to enable offline mode then set offlinequiz to 0

You will also need to add links to the appropriate pages. There are two buttons
already provided for this "onlinebutton.png" and "offlinebutton.png". These
should be linked to index.pl (for the online quiz), and offline.pl (for the 
offline quiz).


Step 8 - Add the questions
---------------------------

Add the questions by logging on with the admin user name at
/cgi-bin/quiz/admin/index.pl

You must add at least one more question than the number of questions in the test



Step 9 - Customise the template files
-------------------------------------
The files in the template directory are html files that can 
be customised to fit in with your site design. Be careful if you 
change any of the entries surrounded by %% %%, which are variables
that are dynamically inserted by the scripts.

I would appreciate it if you would leave the link to penguintutor.com in the 
footer section, or include a link from elsewhere on your web site. This is 
not a mandatory requirement, and can be removed.

The quiz will now be installed and ready to use at: 
/cgi-bin/quiz/index.pl

Step 10 - Test your site
------------------------
You should now be able to test that the quiz is working.
Any problems you can contact me on the PenguinTutor forums at:
http://www.penguintutor.com/forum/

Once it is all complete then you can publicise your new quiz. It would be nice 
to hear of any sites that use the quiz engine, again post on the quiz forum at:
http://www.penguintutor.com/forum/

