9 August 2011        dSurvey

This directory contains dSurvey for WAMP: a javascript/xml package for
implementing "dynamic surveys".Several of it's subdirectories MUST 
be web accessible!

**  For installation instructions, see dsurvey\docs\INSTALL.TXT.
**  For notes on setting up mySql, see dsurvey\readme_mysql.txt
**  For documentation, see dsurvey\docs\dsurveyGuide.htm
**  Hints on installing the PEAR e-mail package: dsurvey\docs\pear_email.txt

Note that the bulk of work done by dSurvey is done via javascript
scripts running on "particpant" or "administrator" machines.

However, dSurvey has a server-side component also.
The server-side component depends on what web server you are using.

  Windows/Apache/MySql/Php (WAMP):
        uses the .PHP files in /dsurvey/admins/phps and dsurvey/client/phps.

dSurvey concepts:

  * administrator
      A single individual who is administering a  survey "session" -- for
      example, modifying on-the-fly what questions are asked, or instructing
      particpant's  to advance to a new web screen. The administrator uses a
      "control panel" to administer the survey session.

   * instrument
       A set of files that specify the actual contents of a survey.
       This includes html code, html code that can include dynamic elements 
       that allow web pages to be participant specific, and changeable
       on-the-fly. The set of files that comprise a given "survey instrument" 
       are used as templates -- they are never modified by dSurvey.

   * participant
        An individual who is taking the survey (or is part of an experiment).
        There are typically many particpants in a given survey.
        "Particpants" are actually a combination of an actual indivdual 
        answering questions on a web page, and a javascript program 
        (a "client") running on the individual's web  browser.


   * session
       An actual working survey (or experiment) is called a session.
       Sessions are based on instruments -- there can be several active 
       sessions that use the same  instrument.  
       Operationally, this means that the files that define a "session"
       are based on files that define the "instrument" that this session is 
       implementing.


   * instrument
       A set of files that specify the actual contents of a survey.
       This includes html code, html code that can include dynamic elements 
       that allow web pages to be participant specific, and changeable 
       on-the-fly. The set of files that comprise a given "survey instrument" 
       are used as templates -- they are never modified by dSurvey.

Files in dSurvey root directory:

DSURVEY.HTM     : the default home page. 
                    This can be customized to point to a list of currently active sessions.
ADMIN.HTM       : the "adminstrators" home page.
                    It conains links to pages in the ADMINS directory


Directories in dSurvey.

Most of these directories are "under the hood" -- they contains files and 
information that are NOT meant to be read (or modified) by the typical 
survey administrator.

In fact, the only directory that is typically changed by a human being
is INSTRUMENTS -- its where survey instruments are stored.

Note: directories that should be web accessible (by participants) are:
    CLIENT, IMAGES, INSTRUMENTS, LIB, and PINFO.
Some of these contain session-specific subdirectories, that can be made
accessible on a participant-specific basis.


ADMINS    HTML files used to administer and otherwise work with dSurvey.
          They are linked to in the admin.htm "administrative home page"

          ADMINS does NOT have to be web-accessible by participants.
          In fact, it probably should NOT be.

CLIENT    HTML files used to join a survey session, and to load an instrument
          on a  participant's browser.

          CLIENT must be web-accessible by participants.

DATA      Temporary and transient "working" data.
          DATA contains "session specific" subdirectories.
          These files are used to store highly changeble session status 
          information, particpant status, and other transient information.

          DATA does NOT have to be web-accessible by participants.

          Note: this DATA subdirectory has been deprecated (mySql databases
                are used instead)

DOCS      Documentation files for dSurvey. These are meant to be read by
          survey designers and administrator

          DOCS does NOT have to be web-accessible by participants.


IMAGES    Graphics files used by dSurvey.

          IMAGES should be web-accessible by participants.

INSTRUMENTS  The instruments.
          Each instrument is stored in a seperate subdirectory under
          INSTRUMENTS. In addition, the INSTRUMENTS directory  contains
          "instrument descriptor" XML files.

          INSTRUMENTS must be web-accessible by participants.
          However, one can limit access to specific subdirectories
          under INSTRUMENTS

LIB       Contains generic javascript libraries (and CSS style sheets) that
          will be read by survey participants and the survey administrators.

          LIB must be web-accessible by participants.

          Note: each instrument directory can also contain a LIB subdirectory,
                which is used for javascript libraries (and css style sheets)
                that are specific to that survey instrument.


PINFO     Parameter files that are "participant accessible".
          PINFO contains "session specific" subdirectories.
          These files are used to store non-changing session information, and
          session information that changes slowly (say, after a round is
          completed).

            PINFO must be web-accessible by participants.
            However, one can limit access to session specific subdirectories
            under PINFO


SESSIONS   The sessions.
            Each session is stored in a seperate subdirectory under SESSIONS.
            These files specify session specific basic data, such as the
            default parameters for the survey.
            Submitted data is also stored in these directories.

            SESSIONS does NOT have to be web-accessible by participants.


TOOLS     A few miscellaneous programs.

            TOOLS does NOT have to be web-accessible by participants.
            In fact, it probably should NOT be (i.e.; it contains an email
            sender that could be exploited).



