4 March 2011

This directory contains dSurvey: 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 documentation, see dsurvey\docs\dsurveyGuide.htm

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.

Examples:

  srehttp/2 for OS/2  :
        The dsurvey.cmd, and dsurveySetup.cmd, "addons", 
       should be installed in \sre2003\srehttp2\addon\dsurvey

  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 administartor.

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


ADMINS      HTML files used to 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.


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 session 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.


SREHTTP2  Files used to support dSurvey when run on the SREhttp/2 web server.

            SREHTTP2 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).



