
Description of the INSTRUMENTS directory of dSurvey.

The INSTRUMENTS directory is where dSurvey instruments should be stored.

Basically, each instrument should have:

  a) a "instrument descriptor" file in this (INSTRUMENTS) directory. 
     For example: myExperiment.XML.
  b) a set of directories for storing files that specify this instrument

  Technical note: some of these directories MUST be web accessible -- 
                   see the bottom of this file for the details.

In this descrption, assume that you created an instrument using the 
Create An Instrument option on dSurvey's main administrative page (/dsurvey/admin.htm). 

  *  Advanced users, who use other means of creating an instrument (and other 
     means of creating an instrument descriptor file) may wish to review the 
     advanced user notes at the bottom of this document.

  * The administration page has several utilities that can be used to modify the
    files listed below.

The following subdirectories and files should exist for every instrument. For simplicity sake, 
assume that the instrument is "ENAME".

file:

      instruments\ename.xml                 : The instrument descriptor file

subdirectories:  
     instruments\ename             : location of root page, modules, specifications, etc. 
                                           Note that all sessions  created from a given instrument 
                                           use these files.
     instruments\ename\specs     : location of SPEC files
     instruments\ename\modules  : location of module files
     instruments\ename\lib         : location of optional, instrument-specific, .CSS and .JS files
     instruments\ename\old        : location of old stuff (this can subdirectory can be deleted 
                                            with no ill effect)
       

Files in instruments\ename include:

    instruments\ename\allowedUsers.xml  : 
        The "allowed uers file" 

    instruments\ename\control.xml        :
      The "control panel" program. 
      By default, a "simple" control panel program is created, that can/should be customized.

    instruments\ename\describe.txt      : 
         Text description of this instrument.
         Typically this would contain descriptions of the variables.

    instruments\ename\params.xml        : 
        The "general parameters file" (same for all participants)

    instruments\ename\reference.xml     : 
        The "reference parameters file" (used to create participant specific parameters)


Other files

     instruments\ename\modules\modules1.xml   :
          By default, an emtpy file. It can be used for storing instrument specific modules.

     instruments\ename\specs\specs.xml    :
         A simple SPEC, designed to be used with the default (simple) control panel
         program, to start a dSurvey session. It can, and should, be customized

     instruments\ename\specs\specs_elements.xml    : used by the specs.xml mentioned above
                      
Scenario files

    Scenarios files, and scenario list files, can be created using the 'Create a scenario file
    for an instrument' action on the main administrative page. 

    These will files will be saved to the insturment directory: scenario files always start with
    'sc_',  and scenario list files always start with 'SL_'.
                

What happens when a session is created?

  When a session is created from an instrument, several session-specific subdirectories 
  will be created.
  And many of the above files will will be copied to these session-specific subdirectories.

These include (assume the name used for a session is "mySession"):

     sessions\mySession.XML   :
           session specific descriptor file (this is a copy of the instrument descriptor file, which
           can be modified to control the default parameters for this session)
     sessions\mySession       :
           directory for storing session specific parameter files, results (i.e.; submitted data), etc.
     pinfo\mySession          :
           directory for storing "client accessible" parameter files (for this session)
     data\mySession           : 
           directory for storing session-specific temporary data


On web accessibility.

  Some of these directories must be web accessible -- the participants browsers will be 
  requesting files directly from them. 

These are (using the above examples of instrument and session names):

    instrument\ENAME\*
    instrument\ENAME\modules\*
    instrument\ENAME\specs\*
    pinfo\mySession\*
and
     sessions\mySession\*
     sessions\mySession.XML   

On projects:
   An instrument name can have the format:
      $aproject_aname
  In which case, the "aproject" is the "prjoject" that the "aname" instrument "belongs to".

  "Projects" are used to form a hierarchy, with instruments being general (not in a project),
  or "in a project".

  This is simply a way of simplfying display, when there are lots of instruments.
  Note that sessions can be created in projects that have the same name as the instrument's project, 
  or a different name.

Advanced user notes:

  *  For well documented example of an instrument descriptor file, see dsurvey\docs\sampleDescriptor.xml


  * The instrument-specific versions of the:
        * descriptor file, 
        * general parameters file, 
        * reference data file,  
        * allowedUsers file, and
        * scenario and scenarioList files
    are all used as templates for session-specific versions. 
    That is, what a session actually uses is the session-specific versions of these files.
    And these session-specific versions start out (when the session is created) as copies
    of the instrument-specific versions.
    
  * In contrast, control.xml files, module files, and SPEC files are instrument specific --
    all sessions based on a given instrument will use the same control.xml, module, and SPEC files.

  *  the allowedUsers.xml file is only used if the <ALLOWED_USERS> parameter in the sample descriptor file
     is appropriately set.  For details, see dsurvey\docs\allowsUsers.xml

The following modifications of an instrument descriptor file can be used to effect 
what files and subdirectories are used. In general, we do NOT recommend them!

  *  The name of an instrument's "file storage" subdirectory:
                <NAME> ... </NAME>

  * The name of the control panel program:
          <FILE value="controlFile"> ... </FILE>

  * The instrument-specific "home page":
                <HOME_PAGE> .. </HOME_PAGE>
     For well documented example of a dSurvey an instrument-specific home page, see dsurvey\docs\sampleHomePage.txt

  * Parameter files, such as the general and reference parameter:
        <file name="parametersFile"  type="DATA" contains="GENERAL" >...</file>
        <file name="ticketData" type="DATA" contains="REFERENCE" >... </file>
       


Modified 22 February 2011
