-----------------------------------------------------------------
|           MANUAL for the Decision Assistant Applet
|----------------------------------------------------------------
| Created by Daniel Broschart
|   for Thaweesak Taekratok
|   for his thesis project.
| 
| Certain algorithmic theories were developed by
|   Thaweesak Taekratok.
|
| Date of revision: 12/1/01
| Contact info: Daniel Broschart <dan@foolfactor.com>
|       www.foolfactor.com
|
| This file and the associated files documented in this file are 
|                                      (c) 2001 Daniel Broschart
-----------------------------------------------------------------


------------------
    OVERVIEW
------------------
  The Decision Assistant Applet provides a complete web based solution for viewing
and updating perspectives on any topic, as well as displaying the rankings of any
defined solutions to the issue being discussed.

  This solution was created to work with the Research Project Script created by
Marcus Stromberg <stromb@medstud.gu.se>.



------------------
   REQUIREMENTS
------------------
Server Requirements:
	perl 5+
	php 3+

Client Requirements:
	java 1.1


  
------------------
   INSTALLATION
------------------
Client:  No client side installation necessary.

Server:
In the same root folder of the other perl scripts for the project (probably cgi-bin/)
place the following files there:
	tester.zip            # The code for the applet itself.
	appletmanager.cgi     # Run this code to enable or disable the applet, or set
                          the alternative priorities. 
	disableapplet.cgi     # Used by appletmanager.cgi, it disables the applet.
	enableapplet.cgi      # Used by appletmanager.cgi, it enables the applet.
  setpriorities.php     # Used by appletmanger.cgi, it manages the priorities.
	tak.php               # Called by the client program to communucate with the server.

In the stage two subfolder of the perl scripts folder (probably cgi-bin/stagetwo)
place the following file there:
  alternatives.txt      # Contains a the names of the alternatives.  
  
In whatever directory you display your html pages place the following files there:
	live.html             # This page displays the applet that uses the REAL data.
	tester.html           # This page displays the applet that uses simulated data.
		
Make sure that the file permissions for all of the above files are 755 (rwx r-x r-x).

The following files are automatically generated:
  In whatever location as specified by tak.php, the file
    alternativePriorities.dat
  will be created (probably in /cgi-bin/database).


  
------------------
  CONFIGURATION
------------------
You may make changes in the following files:
	live.html         /thesis/live.html
	tester.html       /thesis/tester.html
	tak.php           /thesis/cgi-bin/tak.php
  alternatives.txt  /thesis/cgi-bin/stagetwo/alternatives.txt
  NOTE: Be very careful with any changes to tak.php one!


--- live.html and tester.html ---
  /thesis/
The instructions for the modifications you can do in live.html and tester.html are
the exact same.

In the html files you will see code similar to the following:

   <APPLET
    CODEBASE = "cgi-bin/"
    CODE     = "tester.DecisionAssistant.class"
    ARCHIVE  = "tester.zip"
    NAME     = "TestApplet"
    WIDTH    = 200
    HEIGHT   = 130
    HSPACE   = 0
    VSPACE   = 0
    ALIGN    = top
   >
    <!-- Nice looking values for baseColor:
      #e07020 (or lighter)  and  #80b0ff
      #c0c0c0
      grid: #5080e0  #456398
      graphAreaHeight: 165 or bigger.
      graphBarBackgroundColor: #b0b0b0 #c0c0c0
      simuUsers: 1 through 10
      userNameColor: #500000
      otherNamesColor: #005000
      graphBarColorSequence: "#456398, #469886, #979846, #985946, #984686"
    -->
      <param name=baseColor value=#80b0ff>
      <param name=desktopColor value=#c0c0c0>
      <param name=userNameColor value=#500000 >
      <param name=otherNamesColor value=#005000 >
      <param name=gridColor value=#456398 >
      <param name=graphColor value=#b0b0b0>
      <param name=graphBarColor value=#456398>
      <param name=graphBarColorSequence value="#456398, #469886, #979846, #985946, #984686">
      <param name=graphBarBackgroundColor value=#c0c0c0>
      <param name=scriptName value=tak.php>
      <param name=simu value=false>
      <param name=simuUsers value=3>
      <param name=debug value=false>
      <param name=title value="Decision Assistant">
      <param name=mainWidth value=740>
      <param name=mainHeight value=751>
      <param name=graphAreaHeight value=365>
      <param name=graphBarHeightRatio value=75>
   </APPLET>

CODEBASE: The directory relative to the html file where the ARCHIVE exists. (cgi-bin/)
CODE: The name of the class to execute in the ARCHIVE. (tester.DecisionAssistant.class)
ARCHIVE: The name of the zipfile that contains all the applet's classes. (tester.zip)
WIDTH: The width of the applet that appears in the browser. (200)
HEIGHT: The height of the applet that appears in the browser. (130)
PLEASE NOTE: The WIDTH and HEIGHT do NOT specify the dimensions for the part of the
  applet that is launched outside of the browser.
NAME, ALIGN, HSPACE, VSPACE: Not important. Refer to any HTML and CSS documentation you
  have for thesis items.

<param name=baseColor value=#c0c0c0>: The main background color for the applet that
  appears IN the browser.
<param name=desktopColor value=#c0c0c0>: The main background color for the applet window
  that pops up out of the browser.
<param name=userNameColor value=#500000 >: The color of the currently logged in username 
  (email) in the grid area.
<param name=otherNamesColor value=#005000 >: The color of all of the other usernames
  (emails) in the grid area.
<param name=gridColor value=#5080e0>: The color of the gridlines in the pop-up window.
<param name=graphColor value=#b0b0b0>: The background color of the bar chart.
<param name=graphBarColor value=#456398>: The color of the bars in the bar chart.
<param name=graphBarColorSequence value="#456398, #469886, #979846, #985946, #984686">:
  This is a  list of colors	separated by commas that can be any number of colors, which
  make up the various colors assigned to each user. These colors match users with their
  individual weight bars in the graph. If there are more users than	colors, than the
  colors will simply repeat.
<param name=scriptName value=tak.php>: The filename of the PHP file that the applet
  uses to communicate with the server.
<param name=simu value=false>: If set to 'true' then the applet will use real data
  from the server. If it is set to 'false' then it will use simulated data, and not
  attempt to connect to the server. Note: The only difference between the 'live.html'
  file and the 'tester.html' file is in this one setting, with 'live' being set to
  false, and 'tester' being set to true.
<param name=simuUsers value=3>: The number of users to simulate in the applet when
  it is in simulation mode. Valid values are 1 through 10.
<param name=debug value=false>: If true the program outputs extra code to the console.
<param name=title value="Decision Assistant">: The words that will appear in the title
  bars of all applet windows.
<param name=mainWidth value=540>: The width of the pop-up window with the charts and graphs.
<param name=mainHeight value=551>: The height of the pop-up window with the charts and graphs.
<param name=graphAreaHeight value=365>: This is the height of the area for the bar graphs.
<param name=graphBarHeightRatio value=75>: This is a value that represents the percentage
  of how vertically	wide the bars in the graph will be. A value of 100 will result in no
  horizontal gap between the bars. A value of 50 would make the bars half as vertically
  wide as when the value was at 100.


--- tak.php ---
  /thesis/cgi-bin/
In tak.php the only time you will need to modify the following options will be
if the folder structure is different from the standard installation.

Near the top of the file you will see:

    $dataDir = "answersone/";
    $priorityDataFile = "database/alternativePriorities.dat";
    $accountFile = "database/accounts.dat";
    
These are variables that specify the locations of various files relative to
the location of tak.php.

$dataDir: The relative folder in which the answer files are located.
$priorityDataFile: The location of the file to use to store the alternative priorities.
$accountFile: The relative location of the data file that holds the users'
  login account information.
  
  
--- alternatives.txt ---
  /thesis/cgi-bin/stagetwo/
This file is used for specifying the names of the alternatives. This file must be
setup before before you assign priorities, which is described later. 

The file starts off with the alternatives listed with one on each line.
The list of alternatives is terminated with a line consisting of the text:
ENDOFDATA
on a line all by itself.

Example of how the file should look:
Alternative 1
Alternative 2
Alternative 3
ENDOFDATA


  
You may also modify ALL other parts of the HTML files as you like, to make it
appear how ever you want.

The live.html and/or tester.html could very well be generated from a perl script
in other parts of the thesis project if it is so desired.



------------------
    OPERATION
------------------
This applet is to be used after stage one of the project has been finalized.

--- ADMINISTRATION ---
The administrator needs to edit the alternatives.txt file to make sure all of
the alternatives are set. Then after all of the stageone html files and the
questions.txt file are setup, see the perl manual (manual.txt) for information
on this, you can setup the alternative priorities.

To set the priorities, the administrator should open the appletmanager.cgi file
in their browser, which can normally be reached from the admin page. This is usually
located at something like http://www.goodlucktoday.com/thesis/admin/ and look for
the link to the applet manager. Then the admin should then be prompted to enter in
their password. When you are at the applet manager page click on the link titled
"manage the priorities," enter in the desired priorities, and then click submit.

When stage one is fully completed the administrator should open the appletmanager.cgi
file again.

Then the admin should login with their password, and then click on the link to
ENABLE the applet.

All of the users should then be notified that they should visit the applet page,
normally located at http://www.goodlucktoday.com/thesis/live.html depending on
your installation.

Then after the users are done with the applet the admin should return to the
appletmanager page and click on the link to DISABLE the applet.


--- CLIENT USER INTERACTION ---

LOGIN:
The users will be able to login to the applet after it has been enabled by the
administrator with their email address and password that they used before in the
html (perl generated) pages.

DISPLAY:
They will see a tabbed display of their answers (shown in a different color text
from all the other answers) for each comparison.  They will see a bar graph
representing the current combined values for each item in the comparisons. There
will also be a bar graph showing the current rankings of each alternative.

INTERACTION:
The users can click a location or drag answers up and down to change answers.
To select a different comparison just click on a different tab at the top of
the applet window.

The users will be able to see the results of changing their answers and other
users answers in the applet, and view how the overall results change. The users
will be able to save changes to only their answers on the server by clicking the
"Update Your Answers" button. The users will be able to click the "Refresh Data"
button to update their local copy of the data with the newest values stored on
the server. This should be done after users have been changing their answers.

If at any point a user's answer if found to be missing, a warning will notify the
users of exactly which answer by whom is missing, and will default it to the middle
value (the value of "Equally").



-------------------------
Daniel Broschart (c) 2001