============
PHPESP GUIDE
============

GETTING STARTED GUIDE
---------------------

This document is divided into two main sections. The first section is
for general users. It explains how to use this tool to create a survey,
test it, and incorporate it into a web page. The second section is for
administrators. It explains how to manage a group of related users, and
to use the access control system.

,-------------.
| USERS GUIDE |
`-------------'

There are three basic things that users do: make surveys, deploy
surveys, and retrieve or export the data.

Making Surveys:
---------------
This is a straight forward procedure. Begin with
    * Create a New Survey
and follow the forms and prompts through the procedure. When you have
made a survey you can use
    * Change the Status of a Survey
to put the survey in ``Test'' mode, or go right on to deploying it.

Deploying Surveys:
----------------
After a survey is made (and tested), you can deploy it. This is as
simple as going to
    * Change the Status of a Survey
and clicking on ``Activate''. There are two options for the deployment
of a survey: one is to embed it in a customized HTML page, or to use
the automatic template (which is very plain and simple). To use the
automatic template, simply use the URL that was given to you on the
``Finish'' tab. If you want to have the survey embedded on some custom
web page insert the PHP tag that was given on the ``Finish'' tab in the
desired place in your HTML file. Please make sure the HTML file you put
that code in has a ``.php'' extension!

Retrieving Data:
----------------
For any survey that is in Testing, Active or Ended you can go to
    * Export Data to CSV
and download a copy of the data from your survey. The ``download''
option will allow you to save the data on the computer your web browser
is running on, otherwise the data is saved to a file on the web server
(typically in the /tmp directory). It is recommended that you use the
``download'' option.

Other Actions:
--------------
You can also make copies of surveys, which is very handy if you want to
change a survey that has already left the Edit/Test phase. Copying
copies the survey questions, none of the collected data is copied. A
copy of a survey is placed in ``Editing'' mode.

You can test a survey, which just lets you collect data and make sure
it works as desired.

You can view tabulated results in a ``pretty'' format.

You can also view a survey report, which may be useful to help
interpreting the data collected.

,----------------------.
| ADMINISTRATORS GUIDE |
`----------------------'

Before beginning administration you must understand the user/group
relationship. There are three classes of users. ``Superusers'' (that is
you, the Administrator) have complete control in the Administration
Mode. Designers are the users who will be creating, deploying, and
analyzing surveys. The third class is the ``Respondents'', these
accounts are for private surveys (surveys which require a user to login
before entering data). Each of the Designers and the Respondents is
associated with a group. It is expected that a group will contain
members of a similar area. For example there may be a group for a
department, or a club, or just for some arbitrary group of people who
are working on a similar subject. There may exists an unlimited number
of groups.

There are two main levels of administration. The highest level
(``superuser'' level) lets you control all users, and all surveys. The
second level of administration is a group manager. A group manager has
similar control to the superuser(s), but limited to the subset of users
(and their surveys) in their group.

Superusers:
-----------
The ``superusers'' are users who are a member of the special group
``superuser''. As a superuser, your responsibility should only be to
create new groups and create group managers. Once a group manager has
been created for a group, that user should be able to control all
aspects of that group. However any action that is described below in
the group manager section can be performed by a superuser, but a
superuser is not restricted to actions in a group.

The superuser(s) will see the following administration options on the
main menu:
    * Manage Designer Accounts
    * Manage Respondent Accounts
    * Manage Groups

Manage Groups is very simple. This option simply lists the existing
groups and has a form to add a new group. Group names should be short,
and should not have spaces. Good examples of group names are: ITS,
ProjectX, WebTeam, etc. The description of the group is free form; you
may enter any text you wish but please make it understandable.

Manage Designer Accounts lets you add and remove users from groups, and
change their permissions in each group. The page for this option lists
all the existing user accounts. You can sort by Name or Group by
clicking on the column heading. By clicking on a username, you can edit
that entry.

Superusers should read the next section as well to learn the permission
levels.

Group Managers:
---------------
Group managers have full control over a group. This means that they
have permission to perform all user functions, such as editing,
testing, releasing and archiving. A group manager also can add and
remove users from their groups.

There are four basic user permission options, and two administration
permission options. The user options are:
    * Design Surveys
        Allow the user to create, edit and test surveys. This option is
        on by default, and is probably desired for most situations.
    * Change Survey Status
        This lets a user change the status of a survey. Essentially
        this gives them the ability to release, end, and archive
        surveys.
    * Export Survey Data
        Users with this flag, have the option to download the data
        collected from a survey.
    * Group Editor
        By default, users can only perform any of the three actions
        above on their own surveys. If the Group Editor flag is on, the
        above permissions are widened to include all surveys created by
        members of the group.

The other two options set administration flags:
    * Administer Designers
        This grants the user permission to change flags on users in
        their group, and to add new users to the group.
    * Administer Respondents
        Allows a user to add users to the list of allowed respondents,
	within their group.

----
$Id$