XHMTL extentsons for dSurvey || dSurvey extensions: secondary features

## dSurvey: using Specification Files

Contents
- Introduction
- 1a) Why modular surveys
- 1b) Some definitions
- 2) Getting started
- 3) Structure of SPEC files.
- 3.1.a.0 <include>
- 3.1.a. <init>
- 3.1.b.i. <calls>
  3.1.b.ii <attributes>
  3.1.b.iii. <use> (<set> and useStyle)
- 3.1.c. <sub>
- 3.1.d. <comment>
- 3.1.e. <section>
- params
- if
- create
- group
- event
- content
- Events
- Exec
- Button
- Timer
- Query (and Notify)
- eventActions (`call,submit,query,update,goto,...`)
- How does it work?
- Notes on the logical equation
- Appendix 1: Other documentation files
- Appendix 2: Definitions
- Appendix 3: Synposis of XML module files.
- Appendix 4: Session variables and functions that use them
- Appendix 5: Using IF logic
- Appendix 6: Using equations and functions (order of processing)
- Appendix 7: Converting HTML files to XML document files
- Appendix 8: The base-web page
- Appendix 9: The SUBMIT event action
- Appendix 10: simpleHistory details
- Appendix 11: recoverPrior details
- Appendix 12: message details
- Appendix 13: Somewhat deprecated features

  Introduction
  The dSURVEY software package supports "modular" surveys. By "modular survey", we mean a survey instrument that is built using discrete blocks of extended XHTML code -- each of these blocks is what we call a "module". Building with these modules is, put too simply, a matter of listing what modules comprise each page of the survey instrument, when and how to display each of these modules, and using extensions to determine what other actions should be taken at various times (such as the action of submitting results to a server).

  In this document, we describe how dSurvey specification (SPEC) files are used to accomplish this. These SPEC files (which are XML files) allow you to implement fairly complex instruments without the need to write fancy javascript (or Java, or Active-X, or...) code.

  SPEC files are designed to work with the dSurvey's XHTML extensions. More ambitious programmers might also find the procedure library documentation useful!

  dSURVEY does not contain any GUI-like (window'sy) instrument building tools. You, the survey designer, will need to write text files using your favorite text editor (such as Window's NOTEPAD program).
  More importantly, the more you want to do the more you will have to think like a programmer -- which means creating and using variables, and using IF logic. And that's is where dSurvey's XHTML extensions & SPEC files kick in -- it provides a fairly straightforward syntax, and a simple set of programming tools, that let you make dynamic instruments without worrying about how it all works.
  1a) Why modular surveys?
  The key design goal of modular surveys is to efficiently construct complex, dynamic survey that require minimal commitment of server resources. This means that the choice of which page to display next, and what the contents of this page are, should not require a lot of server processing.

  Modular surveys move as much work as possible to each participant's machine. In addition, modular surveys use XML and javascript scripting tools to implement the dynamic presentation of the several web pages that comprise a survey instrument (often several web pages, repeated a number of times).

  Details on dSurvey philosophy & limitations
  1b) Some definitions
  Survey's modular survey's are based on an architecture, on a way of organizing pieces in a hierarchical fashion. The following quick definitions define this architecture: see the appendix for longer defintions.

  Before delving into the guts of this document, it is HIGHLY RECOMMENDED that you understand these terms -- read the appendix if you are at all unclear.

  Module | Modules contain what the browser displays. In particular, modules contain XHTML code, that can also contain special dSurvey tags & elements that support dynamic display.
  Group | A set of modules; that comprise a web page. This set can contain one, or many, modules
  Section | A set of groups, that comprise a connected series of web pages. To incorporate new information, a new section is displayed.
  Events | A group-load, button, server directive, or timer that causes new group, or new section, to be displayed.
  Event actions | A set of actions that are taken when an event occurs (such as: display a new group when a button is pushed)
  Functions | Javascript functions can be called to modify the contents of a group.

  2) Getting started
  To create a modular survey you need to write a dSurvey specification (SPEC) file. This document describes the syntax and structure of SPEC files.
  In addition, you will need to....
- Write module files.
- Create parameter files. See the dSurvey guide for more details on the above. You might also find useful this template of a dSurvey web page.

  3) Structure of SPEC files.
  SPEC files are structured as XHTML files, and must adhere to all the rules that apply to XHTML (transitional) files. The basic structure of a SPEC file is:
  <?xml version="1.0" encoding="UTF-8" ?> <instrument> <include value="xmlFileName" /> <init> .... </init> <sub> .... </sub> <comment> .... </comment> <calls> .... </calls> <attributes> .... </attributes> <use> .... </use> <section> ... </section> </instrument>
  where:
  1. start with: `<?xml version="1.0" encoding="UTF-8" ?>`
  2. 2nd line: `<instrument>`
  3. final line: `< /instrument>`
  And in between the 2nd and final lines ...

  `<include> value="xmlFileName" />` | specifies a SPEC file, or a `sub`routine, to be inserted into the spec file
  `<init> ... </init>` | specifies "module files" to be downloaded from the server, and session variables to set. Only one `<init>` ... `</init>` can be specified in a SPEC file.
  `<calls>` ... `</calls>` | Optional. Used to specify equations to evaluate & functions to call when specified sections and groups are displayed. Only one `<calls>` ... `</calls>` can be specified in a SPEC file.
  `<attributes>` ... `</attributes>` | Optional. Used to assign attributes to elements in the modules, using `id` or `name` attributes specifed in these elements. Only one `<attributes>` ... `</attributes>` can be specified in a SPEC file.
  `<use>` ... `</use>` | Optional. Used to specify information used with dSurvey's special tagnames. Only one `<use>` ... `</use>` can be specified in a SPEC file.
  `<sub name="subname" >` ... `</sub>` | Optional. Used to define XML elements that can be included elsewhere. That is, the contents of the XML element can be included elsewhere, using `<include >` You can define zero, one, or many `sub`routines.
  `<section>`...`</section>` | The heart of SPEC files. You typically define several `<section>`...`</section>`, with each "..." containing a number of other components. In particular, within each `<section>`...`</section>` you will specify `<group>`...`</group>` and other components.

  3.1 The details.
  3.1.a.0 <include>
  `<include file="xmlFileName" sub="subName" okMiss="1" />`

  is used to include an XML file or a subroutine. Either `file=` or `sub` should be used, but not both.

  If `file="fileName"` is used...

  - The file (`XmlFileName`) will be retrieved from the server (except if file starts with a ~ ).
  - `XmlFileName` will be retrieved from the same place the SPEC file is retrieved from.
    This means that it will be retrieved from the `specs` subdirectory of the instrument's directory.
    Thus, if the instrument's name is `myInst3`, `<include>` will refer to files in the `/dsurvey/instruments/myInst3/specs` directory.
  - If no such file exists: An error message will be displayed on screen (and in the status area), but processing will continue.
    To suppress the error message, include `okMiss="1"` as an attribute of the `<include>`. Note that a warning message will be written to the status area, and processing will continue.
    Use of a `okMiss` is a convenience when you aren't sure if the file will exist.
  - The file must be a valid XML file
  - It should start with the usual `<?xml version="1.0" encoding="UTF-8" ?>` first line.
  - The first and last tags should be `<inc>` and `</inc>`
  - As with SPEC files, include files must contain valid XML code. That is, you have to follow the usual XML rules (such as having a closing tag for all tags)
  - If there is an error in the XML file, an error message will be written to the screen and to the status area, and processing will continue.
  - The contents of this include file are inserted before the `<include>`
  - The `<include value="XmlFileName" />` is removed

  If `sub="subName"` is used...

  1. The contents of a `<sub> .... </sub>` are inserted.
  Basically, `include` allows you to break a long SPEC file into several components.
- You can put an `<include>` anywhere -- these inclusions are done first!
- However, you can not have an `<include>` inside of an included file, or inside of a `sub`!
- You can have a `<sub>` in an include file.
- `<sub>` can be anywhere -- for example, `<sub>` can be embedded in a `<group>`.
- All `sub` are global (regardless of where they are specified).
- Special naming: if `xmlFileName` starts with a `~`, then the main directory for this instrument will be used to look for xmlFileName (with the `~` removed).
  If you use `~`, you must not use a prefix of a suffix!

  Examples: | Instrument name: myTest In the SPEC file: <include file="~inc1.xml" > Then, the following file will be used: /dsurvey/instruments/myTest/inc1.xml In the SPEC file: <include file="inc2.xml" > Then, the following file will be used: /dsurvey/instruments/myTest/specs/inc1.xml

  Using `~` is a convenience if you want to include components for several files (i.e.; MODULES, SPEC, and CONTROL files) in one include file; which you can then store in the instrument's main directory. stripped off) will
  3.1.a. <init>
  `<init>`... `</init>` is used to:
- Specify one or many "module" files to download from the server. Note that each module file can contain one or many modules.
- Initialize values of session variables.
- Load stylesheets or javascript library files
- Specify one or more simpleHistory table(s)
- Retrieve, from the server, a simpleHistory archive and/or a custom history archive.
- Enable dSurvey's message feature. Recollect that "modules" are simply blocks of XHTML code; that may also contain instructions used for dynamic display of information. Each module has a name, that can be refererred to when specifying "module groups". Appendix 3 contains a brief description of XML module files.
  Note: module files must be located in the `MODULES` subdirectory of the instrument the session is based on. For example (assuming `dSurvey` is installed in `D:\WWW\DSURVEY`:
- The instrument is `AUCTION10`.
- Then, files that describe this instrument will be in, and under: `D:\WWW\DSURVEY\INSTRUMENTS\AUCTION10`
- Sessions based on this `AUCTION10` instrument will read module files from the `MODULES` subdirectory: from `D:\WWW\DSURVEY\INSTRUMENTS\AUCTION10\MODULES`
- Note that `SPEC` files, for sessions based on this instrument, will be in a `SPECS` directory: in `D:\WWW\DSURVEY\INSTRUMENTS\AUCTION10\SPECS`
- And, though not required, stylesheets and javascript libraries can be stored in `D:\WWW\DSURVEY\INSTRUMENTS\AUCTION10\LIB` Exception: using ~ to start a file name
- It is sometimes useful to use a single `<include >` file to contain several types of dSurvey components, such as modules, SPEC file entries, and CONTROL file entries. An easy way to do this is to place the file in the main directory of an instrument.
- To do this, simply start a file name (in `<file>`) with a `~`
- See <include> for details

  Syntax:
  <init prefix="xxx" suffix="yyy" > <call retain="0/1" > equations <call> <file prefix="" suffix=""> module list </file> <history name="historyName"> history specs </history> <load > list of css or js files </load>> <message show="0" > message specs </message> <recover /> <recoverSimple /> </init>
  Note : you can specify as many `<file>` ... `</file>` and `<call>` .. `</call>` as needed.

  where:

  `prefix="aPrefix"` | This is optional. If included, all file names specified will have the value of the `prefix` added to the beginning of the filename.
  `suffix="aSuffix"` | This is optional. Same as `prefix,` but added to the end of the filename.
  <call retain="1" > equations </call> | Process equations (and functions). You can specify, 0, 1, or more `call` in an `init`.
  ... | <retain="1">
  | Optional. If `retain="1"` is specified, all the variables in this `call` will be retained -- the values of these variables will not be discarded when params is processed. That is: if `retain="1"` variables will keep the values they had just before `<params>` is processed. Note that variables that have been retained (`retain="1"`) ... are reread before equations in a `<params>`. are processed before CAP files are retrieved from the server. Hence,

- the values of retained variables can influence the values produced by equations.
- the values of retained variables can be overwritten by values specified in a CAP file.

  #### Hint: using retain with CAP variables

  Summarizing the above: variables that are `retained` will not be reset when a new section starts. In particular, in a `<params>`, a `todo="RESET"` will not remove these variables.

  This can be a useful way of retaining, across "rounds", the values of variables read from a CAP file, without having to re-download the CAP file whenever a new section (with a `<params>`) starts.

  The trick is that when a variable name is `retained`, changes in its value will be retained (until changed again). Thus,
  1. A variable is `retained` with an initial value
  2. A CAP file is read that contains this variable.
  3. The variable will be assigned the value (or values, if the CAP file contains an array of values for this variable),
  4. and these new values will be `retained`.
  Thus, you don't need to re-read the CAP file! There is one drawback: you have to explicitily retain all the variables in the CAP file (that you don't want reset). If there are lots of variables, it might be simpler just to re-read the CAP file when a new round starts (or use `todo="SAVE"` to not reset variables.

  #### Notes:

- Only variable values are retained: any underlying equations are discarded.
- If you:
- want to reset a variable to a default value (say, at the beginning of a new round), perhaps by ...
- using an equation to specify a value then you should not use retain.
  Instead, use another method (i.e.; use <calls>).
- if `prior="NONE"`, all prior values will be retained, hence `retain` is ignored.
  equations A list of equations, or functions; with each equation (or function) on a seperate line.
  Note that these equations are evaluated:
  - At the beginning of the session.
  - hence, before any content is loaded.

  - You can review the order that equations are processed.

  - Special case: initializing an array.
    You can initialize elements of an array by using the following syntax:
    aName[m:n]=aval
    Where...
    - `aName`: array name
    - `m` and `n`: array indices. `m` is the first, and `n` is the last index.
    - `aval`: value to use for array elements m to n.

    Example: | `vvs[1:4]=0` is the same as: | `vvs[1]=0 vvs[2]=0 vvs[3]=0,` and ``vvs[4]=0``

    Note that you if you use `retain="1"`, all of the specified array elements will be retained.
  - Reminder: The `retain="1"` attribute is used to specify variables whose values will be retained from section to section.

  `<file
  prefix="bPrefix" suffix="bSuffix" >` Specifies a space delimited list of XML files that contain modules. These will be downloaded from the server. More precisely, a modified version of the filename (with a `prefix` and/or `suffix` added) will be downloaded.

  You can have zero, one, or many `<file>` elements.

  Notes:
  - You can specify a different `prefix` and `suffix` as attributes of a `<file>` -- these will override (for this `<file>`) any values specified in the `<init>` parent.
  - To suppress use of a prefix and/or suffix by specifying `prefix=""` and `suffix=""`.
  - To specify that the file is in the main directory of this instrument, start the filename with a `~`. Caution: if a `prefix` or a `suffix` were specified in `<init>`, you must also specify `prefix=""` and `suffix=""` in this `<file>`.

  module list A space delimited list of module files (to be downloaded from the server).
  <history name="aname"
  where="divId" >
  history specs
  </history> Specify a simpleHistory. The simpleHistory provides a simple (i.e.; not very fancy) history of a participant's decisions and results. The participant can view this at anytime by clicking a button. button that is created using <history> special tagname.

  Each simpleHistory is displayed in a historyTable. This is simply an HTML table. details ...
  Format of a historyTable
  - the `first column` is used for the round number
  - the 2nd column displays the values of the first variable you specify,
    the 3rd column displays the values of the 2ndt variable you specify, etc ....
  - the `top row` is used for column headers (for example, variable names)
  - the 2nd row displays variable values for the first round
    the 3rd row displays variable values from the 2nd round, etc ....
  Note: Rows are added to the simpleHistory table when a <params> is processed. You can suppress this by inserting a `noHistory="1"` attribute in `<params>`.

  Syntax....

  `name="aname"` | Optional. If not specified, `_default` is used. The power of `name` is that you can set up seperate and independent simpleHistorys; such as a summary History (that displays just the most important variables) and a complete History (that displays a lot of variables).
  `where="divid"` | Optional. If not specified, a popup window (with a name of `simpleHistoryWIndow` is used to display the historyTable. If specified, `divid` should be the `id` of an existing element (typically a `<div>`) -- the historyTable will be written to this element (overwriting any existing content).
  history specs | Optional. Elements used to specify details on how to display the historyTable.

  The simplest use of `history` is just:
  < history />
  This will set up a default simpleHistory, that
- the participant can display by clicking on a button created using the <history> special tagname
- that just displays variables submitted to the server
- that displays them in a table However, you can do a fair amount of specification and format control -- see Appendix 10 for the details.
  `<load >` Specify a space delimited list of stylesheets (`.CSS` and javascript libraries (`.JS`) files to load. Note that you can only specifiy zero, or one, `<load >`.
- These .JS or .CSS files must be located in the `LIB` subdirectory of the instrument's directory.
  Therefore, do not specify paths (file names only)!
- They should have a `.JS` or a `.CSS` extension -- file names with any other extension will cause an error.
- Shortcut: use `*` to specify 4 files:
  1. `instName.js` (where `instName` is the instrument name).
  2. `instName.CSS` (where `instName` is the instrument name).
  3. `myFunctions.js`
  4. `myStyles.css`
  <message >
  <defaultMessage left="leftPos">
  a message
  </defaultMessage>
  <where"> `anid`
  </where>
  <options>
  message options
  </options>
  </message> `<message>` is used to enable the dSurvey message feature. This feature allows participants to send, and recieve, messages from other participants (and from the survey administrator).

  When `<message>` is specified, this feature is enabled.
  - `<where>anid</where>`: Optional. `anid` should be the `id` of an element. When this element is clicked on, a read/send messages window will be displayed. If this is not specified, a default button, at the right-top of the page, is used.
  - `<defaultMessage left="leftpos"> a message </defaultMessage>`: Optional. If specified, use the `a message` as the text of the default button (thus, if `where` is specified, this `defaultMessage` is ignored ).
    The `left="leftpos"` is optional: if specified, it specifies the location (relative to the left edge of the screen) for the default button. Note that the default is `left="61%"`
  - `message options`: a comma delimited list of message options

  Appendix 12 describes the message options. These include:
- Whether to notify the participant when a message is recieved
- Enabling/disabling messages
- Whether to disable sending of messages (but allow reciept of messages)
- etc. Note (as described in Appendix 12) that using `<options>` to specify message options is somewhat deprecated: changing message options via CAP files is recommended. That said, is useful for customizing the message button.
  <recover /> Read the history archive database from the server. This will populate the prior variables internal database; which can then be used to create tables, etc. displaying the client's prior decisions and prior results.
  `recover` is meant to be used when the client is forced to reload the browser (say, due to a browser hang).
  Notes:
- `<recover>` is somewhat deprecated: consider using the <recoverPrior> event action
- `<recover>` populates the prior variables internal database by reading the server-side historyData archive that is created by the administrator (using <uploadData> in a control panel).
- Details of creating a custom History
- <recoverSimple> provides a simpler, but but less powerful, means of providing a participant's history.
- As with `<recoverSimple>`, `<recover>` is meant to be used when the client is forced to reload the browser (say, due to a browser hang).
  <recoverSimple/> Read the simpleHistory archive database from the server. This will rebuild a simpleHistory table.
  Notes:
- Succesful use of `recoverSimple` requires appropriate use of a saveSimple parameter in `<params>`.
- `<recoverSimple>` is best used with explicitily set `<vars>` in the `<history>` option of `<init>`.
- Details of creating a simpleHistory
- <recover> provides a more powerful, but more difficult to specify, means of providing a participant's history.
- As with `<recover>`, `<recoverSimple>` is meant to be used when the client is forced to reload the browser (say, due to a browser hang). Example:
  <init prefix="SVY_" suffix="_VER1.XML"> <load> * </load> <file> intro tickets results </file> <file suffix=""> help.xhtml tips.txt </file> <file prefix="" suffix=""> genericHelp.xml </file> <call> checkScreen=1 </call> <call retain="1" > myBank=10 </call> <recoverSimple /> </init>
  - The following files would be downloaded as module files from this instrument's `modules` subdirectory:
    `SVY_intro_VER1.XML, SVY_tickets_VER1.XML , SVY_results_VER1.XML SVY_help.xhtml, SVY_tips.txt`
    and... `genericHelp.xml` would be retrieved from this instrument's main directory
  - Two session variables will be created: `myBank`and `checkScreen`.
  - `checkScreen` will have a value of 1. But, it will not be retained -- it will be reset when the first params is processed.
  - `myBank` will start with a value of `10`, and will retain its value (it not not be reset whenever a params is processed).
  3.1.b.i. <calls>
  You can use `<calls>` to specify a set of equations, or functions, to call whenever a section, or a group within a section, is displayed. Note that these are called just after the modules are displayed on the page; hence they are called before the special tagnames are processed.

  Syntax:

  <calls > <call for="* section section.group" desc="an optional description" > functions and equations </call > ... <call for="* section section.group" > functions and equations </call > </calls >
  The `desc` attribute is optional: it is used by dSurvey utilities.

  The `for=".."` specifies for which groups and sections the functions and equations specifed in the `<for>` will be called. Basically, when a group or section starts:
  1. all the `<call>` within `<calls>` are examined.
  2. The `for` attribute of each `<call>` is examined.
  3. The `for` attribute should contain a space delimited list of section names or group names.
  4. If the name of current section, or the name of the current group (in the current section), is specifed in this list, or if * is specified in this list, then the equations specifed in the `<for>` are used.
  5. 0, 1, or many `<call>` blocks can be used for any given section or group.
  Example...
  <calls> <call for="*" > ... these are called always Cost=cost*markup profit=Cost * 0.15 </call> <call for="section1 section2" desc="cost stuff" > ... these are called for all groups in section1 or in section2 cost1=cost1a+ (cost1b/irate) newCost=cost1+cost2*1.15 <if value="newCost gt cost" > cMessage='(cost has been recomputed)' </if > </call> <call for="section2.XGroup" > ... this is called only for the Xroup group in section2 <if value="mycost gt cost" > isBig=1 truncCost = trunCosts(myCost,maxCost) </if > </call> </calls>
  Notes:
  - groups are specified using a dot notation: `sectionName.groupName`
  - You can have 0, 1, or more than one `<calls>` in a `SPEC` file.
    It is probably cleaner to have just one `<calls>`in a `SPEC` file.
    But it can be useful to include other `<calls>` via an `<include>` file, say as part of a section+.
  - `<calls>` are typically specified in an instrument's `SPEC_ELEMENTS.XML` file.
  - `<calls>` can be anywhere in the `SPEC` file (though it must be a first level element of the XML file).
  3.1.b.ii. <attributes>
  `<attributes>` is strictly optional. The use of `<attributes>` pays obeisance to the notion that the content of HTML files should be seperated from presentation. `<attributes>` are used to modify attributes, and the value, of XHTML-elements that may be found in the modules.
  You can use `<attributes>` to ...
  1. specify attributes to assign to XHTML-elements
  2. change the value of XHTML-elements

  #### Specifying attributes

  Basically, you can specify attributes directly inside of XHTML elements included in your modules.
  For example:

  <span style="color:blue" > The round is </span> <show class="numShow" var="nowRound" />
  These XHTML elements contain several attributes (such as `class` and `style`). While perfectly valid XHTML (transitional), it is a bit cluttered. And with lots of attributes, it can get very cluttered.

  Thus, for readabilty/aesthetic purposes, it may be useful to remove all the attribute defintions from the XHTML code (from the module) and specify it elsewhere. In particular, in the SPEC file using `<attributes>`!

  To do this, you must add an either an `id` or `name` attribute to the XHTML elements you wish to modify. Thus, the above example could become:

  <span name="nowRound" > The round is </span> <span ID="ShowMe31"> (introduction) </span>
  As described below, in `<attributes>` you would code instructions that refer to `nowRound` and `ShowMe31`. And, these instructions would contain the possibly lengthy attributes. For example:
  <nowround name="1" > <style > color:blue <style > </nowround > <showMe1 > <class > numShow <class > </showme1 >

  #### Limiting the scope of <attributes >:

  When specifying attribute, you can use the `<scope>` modifier to limit when these entries are applied. That is, you can specify which section, or group, a set of attributes applies to. This is useful as an efficiency measure (since it limits the searching and matching the dSurvey software must do). It also allows you to specify the same `<element>` multiple times (say, with different values in different sections).

  #### Syntax of <attributes >:

  <attributes > <scope name="whichSection" > <scope name="whichSection.aGroup" > <anID > <AnAttribute append="1"> attribute value </AnAttribute> </anID > <aName name="1" > <AnAttributeX > attribute value </AnAttributeX> </aName > </attributes>

  where...

  `<scope name="whichSection" />` `<scope name="whichSection.agroup" />` | Optional. Specifies that all following IDs (that are after this `<scope>`) should only be used when displaying the whichSection `section`, or the `agroup` group within the `whichSection` section. You can specify several sections, or groups: just use a comma delimited list.

- You can specify a name, or ID, in several different `<scope>`: the results will be accumulated. Thus, you can specify attributes for elements for a given group (or section) across several different `<scope>`. This is useful when elements are shared by different groups, with lots of overlapping.
- This restriction remains in effect until the next `<scope ... />`
- At the beginning of `attributes`, before the first `<scope >`, the IDs can be used in all sections.
- `<scoper name="0" />` turns off this section specification -- everything following this can be used in all sections (until the next `<scope ... >`)
- Note that there is no `</scope>` -- instead, close the element with a `/>`.
- For large instruments, where you may have many sections and lots of elements per section, liberal use of `<scope>` can increase processing speed.
- Reiterating: using `whichSection.agroup` restricts use to elements in the `agroup` group of the `whichSection` section. In contrast, `whichSection` is less restrictive: it restricts use to all groups in the `whichSection` section.

  Specifying multiple sections: Instead of just one section or group, you can specify that a `scope` apply to several sections (or groups). To do, use a space delimited list. For example:

- `scope name="Tickets1 Ticket2"`
- `scope name="Intro1 Intro2.sec1"` Note that you can freely mix section and group names.
  `<anid>` specifies the id of the XHTML element whose attributes are to be modified. You can specify zero, one or more `<anid>`
  When content is created (in a `<group>`), all its XHTML elements will be checked.
  An XHTML elements whose `id` attribute has a value of `anId` will have its attributes modified.

  `<aName name="1">` specifies the name of the XHTML element whose attributes are to be modified. You can specify zero, one or more `<aNamee>`
  When content is created (in a `<group>`), all the XHTML elements will be checked.
  All XHTML elements whose `name` attribute has a value of `aName` will have their attributes modified.

  name="1" Signals `aName` should be matched matched with `name` attributes.
  Thus: if `name="1"` is not specified, `aName` will be matched against `id` attributes.
  <AnAttribute> specifies the name of the attribute to add (or to append to). Also, as described below, a few special values of `AnAttribute` are used to call functions & equations, or to conditionally set an element's value.
  append="1" Append is optional. If specified, and set equal to 1, then the attribute value will be appended to the current value of `AnAttribute` attribute.
  If the `AnAttribute` attribute does not exist, append is ignored, and an `AnAttribute` attribute is added.
  attribue value specifies the value of the attribute. `attribute value` should not include `"` characters!

  #### Notes:

  - You can specify zero, one, or more than one `<attributes>`. Though it probably is cleaner to not define more than one.
  - You can specify `<attributes>` anywhere in the `SPEC` file (though it must a first level element in the XML file).
  - `<attributes>` is typically specified in an instrument's `SPEC_ELEMENTS.XML` file.
  - Defining the `class` attribute in the SPEC file may be taking seperation of content from presentation too far.
  - The tag names used in `<attributes>` represent either IDs or NAMEs.
  - `id` : must be unique across all XHTML elements that may appear in a section. Although we do not recommend it, XHTML elements in different sections can contain the same ID.
  - `name` : do not need to be unique -- there can be several XHTML elements with the same `name` in a section, or in a group.
  - You can review the order that equations are processed.

  #### A shortcut

  Instead of
  `<AnAttribute> a value </AnAttribute>`
  you can use
  `<AnAttribute value="a value" />`
  3.1.b.iii. <use>
  When working with the special tagnames, one might have to specify a number of features. This is done either by using attributes (in the special tagname), or by specifying XHTML elements (underneath the special tagname). Either method can be quite cluttersome.

  To address this clutter, you can use the `use="aname"` attribute of these special tagnames. This will include a block of elements, a block that is specified within the `<use>` section of your SPEC file.

  Restating: this requires two steps:

  1. In the special tagname, specify a `use="saveName"` attribute.
  2. In the `<use>` section of your SPEC file, specify a `<saveName>` element, under which you can specify any set of elements. These elements will then be inserted under the special tagname (that is, they will become children of the node of this special tagname element).
  Note that this insertion can only be done with the special elements. In contrast, attibute insertion can be done with all kinds of elements.
  Example:
  In the SPEC file ... <use > <qpointsInsert > <start>0</start> <title> Discount to apply to your bid </title> <min> 0 </min> <max> quality_points </max> <change> qpoints_cost[iTicket]=qval*quality_price <if value="offers_used[iticket] ne 0"> zcost=prodCost_used[iTicket] </if> <!-- ignore quality if no offer --> totearn=0 <do for="mth=1,numTickets"> totearn=totearn+earnings_used[mth] </do> </change> </qpointsInsert > </use > and in the module <span style="background-color:#ccccbc"> <value size="4" class="qClass" isNumber="1" use="qpointsInsert" /> </span >
  Notes:
  - it is perfectly legal to simultaneosly specify additional-elements in a <use> section, and under the special tag (the elements in the <use> are appended after the elements directly specified).
  - You can have 0, 1, or more than one `<use>` in a `SPEC` file.
    It is probably cleaner to have just one `<use>`in a `SPEC` file.
    But it can be useful to include other `<USE>` via an `<include>` file, say as part of a section+.
  - `<use>` is typically specified in an instrument's `SPEC_ELEMENTS.XML` file.
  - `<use>` can be anywhere in the `SPEC` file (though it must be a first level element of the XML file)..

  #### Special trick: setting style with `<set>`

  As a shortcut, you can also set the `style` attribute of a set. This is an alternative to specifying the `style` in the `<set>`, or using an entry in the `<attributes>`.

  Syntax:
  <useName useStyle="css_style"> functions, etc </useName >
  The `css_style` will replace whatever style was assigned (in the `<set>` that contained a `use="useName"`). Note that this only works with `<set>` -- for other special tagnames (such as `<value>`), `useStyle` is ignroed.
  3.1.c. <sub>
  <sub> is used to define `subroutines` that can be included.

  When `include sub="subname"` is used, it will copy the contents of a `sub` (to the location of the `include`).

  Syntax: `<sub name="subName" > ... </sub>`

  Note that `name` must be specified.

  Example....
  <sub name="stuffA"> <literal> <h3>Common section header </h3> <em>Don't forget to watch the timer!</em> <p/> </literal> </sub>
  3.1.d. <comment>
  <comment > (or <cmt >) is used to insert a comment. It is an alternative to using `<!-- .... -- >`.

  The main reason for using <comment > is for editing SPEC files using dSurvey's Modify an instrument's control, SPEC, and module files utility. <comment > elements are displayed (in blue). In contrast; `<!-- .... -- >` comments are not displayed at all (a bunch of blank lines will be displayed).

  Example....
  <comment> This is my literal. Perhaps I should use a module instead? </comment> <literal> <h3>Common section header </h3> <em>Don't forget to watch the timer!</em> <p/> </literal> <cmt> Enough for now </cmt>
  3.1.e. <section>
  `<section>` is the heart of SPEC files -- it is used to specify sections, and the module-groups that comprise sections. You typically specify several different sections. Sections consist of one more module-groups. When a section is invoked, the following occurs (note that this is a simplified outline):
  1. If `<params>` is specified, the following are done (in order)
  2. If specified, prior values from the just completed round will be saved to a prior variables internal database
  3. the survey's client-accessible files (either session or round specific) are retrieved from the server, and the variable they specified are processed.
  4. Other variables and equations may also be set.
  5. The module groups are constructed. By using `<if>`, the `groups` in module group, and the `contents` of a group, can be influenced by the current values of session variables.
     Once a section is started, the order and contents of the module groups will not change, even if values of the session variables (used when constructing these groups) should change.
     In other words:
  6. To update the groups in a section, and the content of groups, a new section is typically called (possibly the same section as was just being displayed).
  7. The first module-group is displayed.
  8. The `<attributes>` are checked. Equations may be processed, attributes of selected elements modified , and values of selected elements modified. Note that values can be the content (the `innerHTML`) of a `div` or `span`, or the `value` of an `input`.
  9. If specified, group and section specific equations specified in a `<call >` are processed.
  10. Specified `<events>` are set up -- including execs, buttons, timers, and server-variable lookups.
  11. The browser continues to display the module group until one of the events occurs.
  12. When an event occurs, either a new group is displayed (that is, step `3` is started with a new group), or a new section is invoked (step `1` is started with a new section).
  Syntax:
  <section name="sectionName" > <params get="which" priors="todo" /> <get file="xmlfile" /> equations </params> <create moduleName="newname" tagName="atag" otherAttributes="value" > <content repeat="n" idxTags="tagList" idxClass="classList" desc="short desc"> ... all the content components (see below) </content> </create> <group name="groupName" otherAttributes="value" <if value="logical equation" /> <events value="eventType"> event actions </events> <content otherAttributes="value" repeat="n" idxTags="tagList" idxClass="classList" desc="short desc" > <if value="logical equation" /> <focus value="a string" /> <label show="number name" otherAttributes="value" inHeader="0/1" > short string </label> <literal otherAttributes="value" > valid XHMTL </literal> <gap otherAttributes="value" /> <modules otherAttributes="value" addPrior="0/1" usePrior="1" > list of modules </modules> </content> </group> <group name="groupName2"> ... </group> </section>
  Where ....

  `<section name="sectionName"` | <params> <create> <group>
  | Each section must be given a name. Sections can have `functions`, which are run whenever a new group is displayed. You can `create` new modules. And you must specify one or more `groups`.
  name="sectionName" | each section must have a name. It should uniquely identify the section -- it is used as a target when jumping from another section. The `sectionName` can not be an integer, nor can it start with an underscore (_)
  params & call (section-specific) ....
  <params get="which" priors="todo" noHistory="1" > roundVar="aVarName"1" > saveSimple="1" > equations < get file="xmlfile"/> </params> | Save & reset prior values of all parameters, retrieve CAP files from the server, create a simpleHistory row, and evaluate initialization equations. If specified, `<params>` is always done first -- it does not matter where in the `<section>` it appears. Note that retrieving parameters from the server entails ... Sending a request to the server for a CAP (client accessible parameters) file. The server will send back the requested CAP file(s) (as an XML file(s)). Note that these can contain general variables(that apply to everyone), and participant specific variables. The browser will parse the CAP file, storing values to session variables. The several CAP files: There are two client accessible parameters file that can be easily retrieved: the session-specific parameters, or the round-specific parameters. Session-specfic parameters typically do not changes over the course of a survey session -- therefore, usually they are only retrieved once. Round-specific parameters change frequently, typically at the end of a round. Therefore, they are often read frequently; typically right before the start of a new round. In addition, you can specify other custom client accessible parameters files to retrieve. Shortcut: To save & reset current parameters values, not specify any `equations`, and retrieve just the round-specific parameters file, you can use: <params /> Basically, `<params />` is a shortcut for `<params get="round" priors="BOTH" />`
  priors="todo" | Optional. If specified, `todo` should be one of the following:

- `priors="NONE"`: The default (used if `priors` is not specified). Do not save, and do not reset.
- `priors="BOTH"` : Save all current parameters to the prior variables array, and reset (that is, remove) all of these variables (with a few exceptions).
- `priors="SAVE"` : Just save the current parameters --do not reset. Thus, current variable values will be retained.
- `priors="RESET"` : Reset variables, and do not save.

  #### Notes

- `priors` is processed before the CAP files are read. Thus, values in the CAP files (such as results for the just completed round) will not be saved .
- Hint: to save results for the just completed round, the CAP file can contain dotted variables, that explicitily set variables for a prior round. For example, if round 17 just completed (and round 18 is about to begin), one could find the following general parameter specified:
  <TOTALEARN.17> 21 <<TOTALEARN.17 >
  which means set `TOTALEARN`, in the set of round 17 prior variables, equal to `21`.
- the following session variables are always available (they will be retained even after a reset):
  `myID myNAME myNICKNAME myCONTACT _sessionName _instrument`
- The `_ADDRESSES` variable (that contains a list of participant addresses) is always available (it will be retained even after a reset):
- Variables specified in an <init> with a `retain="1"` will not be reset (even if `todo` equals `BOTH`, or equals `RESET`)
get="which" Optional. If specified, `which` should be one of the following:
- `get="ROUND"` : retrieve the round-specfic parameters file. This is the default
- `get="SESSION"` : retrieve the sesion-specfic parameters file. This is the typically done just once (at the start of the first section)
- `get="BOTH"` : first retrieve the session-specific parameters file, and then retrieve the round-specfic parameters file.
- `get="0"`: the round and session specfic parameters file are not be retrieved.
  This is used when you start a new section, and want to evaluate the initialization equations without updating the parameters file.
Note that if `get="which"` is not specified, then the round-specific parameters will be retrieved.
The `myRoundParams` and `mySessionParams` javascript global variable are used to specify the round and session specific parameters file.
These are typically set in this survey's main html file.

noHistory="1" Optional. If specified, than do not add a row to the simpleHistory table.
Otherwise, if `priors="BOTH"` or `priors="SAVE"` are specified (or if `<params />` was specified), then a row will be added to the simpleHistory table.

#### Notes

assuming that `noHistory="1"` was not specified ....

- Adding a row to the simpleHistory table does not mean it will be automatically displayed on the participant's browser -- the participant will have to refresh the History : by pressing a button created with a <history> special tagname.
- This row is added after:
- `prior` variables are saved, and
- after variables are read from a CAP file(s). Thus, you can include variable names (in the <vars>) that refer to results returned in the CAP file.
- Values of these variables from the most recently completed round are used. Thus, if round `n` is just starting, then values from round `n-1` will be used to create the new row in the simpleHistory table.

roundVar="aVarName" Optional. If specified, than `aVarName` should be the name of dSurvey variable (perhaps one set using a <call>).
`aVarName` should contain the value of the just completed round. Its value will be used to save information when saving prior variables, and when adding rows to the simpleHistory tables.

Note: if `roundVar` is not specified, the `nowRound` variable will be used.
saveSimple="1" Optional. If specified, then in addition to adding a row to the simpleHistory table, a row will be added to the `simpleHistory` archive on the server.

This archive can be retrieved (if needed) by the <recoverSimple> option of `<init>`.
Note that if `noHistory="1"` is specified, then `saveSimple` is ignored.
equations Optional. These equations are evaluated after the XML parameters files are retrieved, and before any group is displayed. Hence,

- these equations are meant to be used for initialization; say, to initialize session variables that may be used in different groups within the section.
- these equations can not be used to modify the contents of a group.
- you can use <if> to control which equations to evaluate
- Equations specified in `params` are processed when the section is first loaded. They are similar to equations processed within <calls>. Thus, use of equations within `<params>` is somewhat deprecated.
- You can review the order that equations are processed.

<get file="xmlfile" > `get` is used to retrieve other, custom XML parameter files. the `xmlfile` should be a filename (of an XML file) that the server has access to.
Note that you can specify many `get` -- they will be retrieved & processed in order of appearance.

Note that the following processing order is used:

1. Session specific CAP file
2. Round specific CAP file
3. Custom parameter files (in order of appearance)
4. Equations

Thus, it does not matter where the `<get />` are placed -- the parameter files they refer to are retrieved before `equations` are processed.

Create ....
<create moduleName="newname" tagName="atag" otherAttributes="value" > | <content>
| Create a new module, starting with an empty `div`. You can have 0, 1, or more `<create>` per `<section>`. `<create>` can be anywhere in the `section` -- they are always processed before the first `group` is displayed. That is, athough typically `<create>` is placed before the first `<group>`, it doesn't effect order of processing if you put them at the end of the `section`.
moduleName="newname" | The new module's name is specified with the `moduleName` attribute. This newly created module can be used later, using the `newname,` in `<group>` or even in other `<create>`, just like a module read from a file.
tagname="atag" | The new modules base XHTML element will be a `DIV`, unless you specify an alternative using the `tagName` attribute.
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the base XHTML element. You can have as many `otherAttributes="xxx"` as you want. Example: `class="bold1" onClick="alert('hello')"`
`<content repeat="n" idxTags="tagList" idxClass="classList" desc="short description" >` | <if> <focus> <label> <modules> <literal> <gap>
| You can specify one, or more, `<content >`, each of which may contain `<modules> <literal> <modules>, etc` components. see below for a description of the `<content >` components, and the `repeat`, `idxClass`, and `idxTags` attributes. Notes: As in `<group>`: you can use `<if>` to control which `<content >` are added to this new module. There is one difference (that used to be crucial, but now is kind of unimportant): When using `<create>`: when processing a `<modules>`, the modules are added directly to the `div` created in the `<create>` That is...: every `<modules>` in a given `<create>` is part of a single `div`. When using `<group>`: when processing a `<modules>`, first a new empty `div` is created, and the modules are added directly to this `div`. That is...: every `<modules>` in a given `<group>` has its own `div`. Why the difference: it lets you use `<create>` to build a dynamic table (however, we now recommend using the `<if>` and other special-tagnames to build a dynamic table). There are a few minor differences: in `<create>`all attributes are ignored (in particular, `addPrior` and `usePrior`> are ignored). in `<label>`, `show="number name"` are ignored (since it doesn't make a lot of sense to add a name/number label for a module that is being created for later use).

Group ....
<group name="groupName" otherAttributes="xx" > | <if> <events> <content>
| `<group>` is used to define module-groups. A group, regardless of how complicated its `<content>` are, will be enclosed within a `div`. One or more `<group>` can be specified in each section. Reminder: A module group consists of modules and other content, possibly javascript function calls, events (used to leave the module group), and targets (used to jump to the module group).
name="groupName" | Optional. A name to use for the group -- used by jumps. This is in addition to a sequence number ("1","2",...) assigned to each group. Thus, `groupName` can not be an integer, nor can it start with an underscore (_).
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the `div` that is the base XHTML element for the group. For example: `class="fancyFonts"`
<if value="logical equation" />
| You can specify one, or more, logical equation that must be satisfied for the group to be used (for the group to be included in the section). You can have 0, or 1 `<if>` in a `<group>` See Appendix 5 for the details.
Events ....
<events> <etype> | <event actions>
| Specify a set of events that will cause the browser to display a different group, or different section. The `eType` should be one of: `exec`, `button`, `timer`, or `query`. There can be zero, one, or several `<etype>` per `<group>` -- though having none would mean you can never change the group being displayed. The event actions allow you to specify what event actions should be taken when an event occurs (say, when a button is clicked). For example: `call` a function, display the `next` section, or `goto` a specific group or section.
Content ....
`<content repeat="n" idxTags="tagList" idxClass="classList" desc="short description" otherAttributes="xxx">` | <if> <focus> <label> <literal> <gap> <modules>
| Specify the content of the module group. Each `<content>` is placed inside of a `div` base XHTML element -- see `<create>` for an alternative. There should be one, or more `<content>` per `<group>`. `<content>` is where the modules (as loaded using <file>) are utilized. You can use IF logic to control what content to include in the `<group>` Any attribute you specify will be added to the `div` base XHTML element (such as "class")
desc="short description" | Optional. A short (several word) description of what this CONTENT contains. Used for debugging.
repeat="n" | The actual stuff specified in a `<content>` can be repeated several times, so that the new module contains several copies of the one (or several) replications of the stuff specified in the `<content>` . `n` can be an integer, or it can be a `varname` (a session variable). If `varname` is used, it must be an integer! The XHTML- elements in each repetition are subject to one modification: an `idx` attribute (with a value equal to 1...n) is added to selected elements ... Note that `repeat`, `idxTags`, and `idxClass` are mostlyt deprecated. We recommend using the `<repeat>` special tagname.
idxTags="tagList" | The tags of the XHTML elements to add (this `idx` attribute to) can be specified as a space delimited string in the `idxTags` attribute. If you do not specify `idxTags`, a default `taglist` of `"INPUT DIV SPAN"` is used (note that case does not matter). Note: to suppress checking tags (say, because you use `idxClass`), set `idxTags="0"`.
idxClass="classList" | The `class` attribute of the XHTML is checked. If any word in the `class` attribute matches (case insensitively) a word in classList, an `idx` attribute is added. Note: if you do not specify `idxClass`, the `class` attribute will not be examined.
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the base XHTML element (such as "class")
<if value="logical equation" />
| Similar to `<if>` "group specific" `<if>`, but controls whether this `<content>` (modules, literals, etc) are included in the `<group>`. See Appendix 5 for the details.
`<focus value="a string" />` | Optional. The browser's focus will be here. If not specified, the browser focus is on the first module in the first `<modules>` Only one `<focus />` is allowed per `<group>` (no error occurs, but the end results are unpredictable). A empty `<span>` is added with an Id of `__MODULEFOCUS,` and a `Class` of `styleModuleFocus`. Other methods of setting the focus
value="a string" | Optional. If specified, the span will contain `a string` (as text). Rather then using `value="a string` to display a short message, we recommend using `<label>`.
`<`label show="number name" inHeader="0/1" otherAttributes="value" > short string </label> | Add a group number, name, or short string as a label. A label will be written in a `<div>`, or to the header. This label can contain the group name, group number, and a short string The display order is: `number + ' : ' + name + ' : ' + short string` (colons only used as needed). If `inHeader="1"` is specified, the label info will be written to the header (to the HeaderMessage area). Otherwise, the label is inserted in sequence (i.e.; after any `literal`, `modules`, etc. that were previously specified). Note that the header is a fixed location -- it stays there as you page up and down. Short cuts: If you dont have `short string`, you can use `<label show="..." />` To just insert a number, using the default style, you can use `<label />`
show="number name" | Optional. Show can have neither, both, or one of the `number` or `name` directives. `number`: show the group number (in this section, as they would be displayed) `name` : show the group name (if one was specified)
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the base XHTML element (such as "class") Notes: if no `class` is specified as an `otherAttributes`, a the `class="styleLabel"` attribute is used (which yields a narrow gray-bordered box using a small italic font). You can add a `name` or `id` attribute (which may be useful for custom processing).
`<literal otherAttributes="xx" >` valid XHTML string </literal> | A valid XHTML string to be inserted as is, in a `<DIV>`. Example: <literal style="font-size:120%" > <h2>List of stuff </h2> <ul> <li> first son </li> <li> second dog </li> <li> last house </li> </ul> </literal>
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the base XHTML element of the `<div>` that contains this `literal`. For example: `class="myComments"`.
`<gap size="nnn" color="acolor"/>` | Insert a gap of nnn pixels height, and background color acolor, to be included as a `DIV` . By default, a `class="styleDefaultGap"` is used as an attribute of this `div`, which (if `size` and `color` are not specified), yields a 100px light gray gap. You can include zero, one, or more, `<gap>` per group. Note: For fancier gaps, use `<literal>` with the desired `otherAttributes`.
size="nnn" | Optional. The size, in pixels, of the gap.
color="ccc" | Optional. The background color ofthe gap. `ccc` is either a color name (eg; `red`), or color code (eg;`#ab99c2`).
<modules otherAttributes="xxx" addPrior="0/1" usePrior="1" > list of modules </modules > | A space delimited list of modules are specified to be added (in order) to a `DIV` base XHTML element. You can include zero, one, or more, `<modules>` per group. Any attribute you specify will be added to the base XHTML element (such as "class")
addPrior="0" addPrior="1" usePrior="1" | Optional -- only used when processing a `<group>`. `addPrior` and `usePrior` work with the prior modules cache. The prior modules cache provides a convenient means of updating content that has just been displayed, with the newly added content recieving focus and/or special styling. The prior modules cache is reset (to empty) whenever a section starts. When a `<modules>` contains a `addPrior="1"` attribute, then all the modules specified by this `<modules>` will be appended to the prior modules cache. When a `<modules>` contains a `usePrior="1"` the current contents of the prior modules cache will be prepended to the list of modules that are specified by this `<modules>`. The prior modules cache can be reset (to empty) if `addPrior="0"` is specified. Note that if both `addPrior="0"` and `usePrior="1"` are specified, then the current contents of the prior modules cache will be used before the cache is reset (to empty). if both `addPrior="1"` and `usePrior="1"` are specified, then the the prior modules and the curren modules will be displayed; and the current modules will be appended to the prior modules cache Note that if `addPrior` is not used, then the prior modules cache will not be modified. Thus, the prior modules cache will only include modules specified in `<modules>` that contain a `addPrior="1"` attribute. Note that nothing else is ever included in the prior modules cache. For example, the contents of `<literal>` can not be included. Furthermore, any attributes (such as `style` attributes) specified in a `<modules>` will not be retained in the prior modules cache. The prior modules cache will be reset at the beginning of a section, or after processing a `<modules>` that contains a `addPrior="0"` attribute. Otherwise, it is not changed. Reminder: inside of a `<create>`, `addPrior` and `usePrior` are not processed (they are ignored).
otherAttributes="xxx" | Optional. Any other attribute you specify will be added to the base XHTML element (such as "class").
list of modules | A space delimited list of modules names. These are module names specified in the XML-modules files read using `<FILE>`, or the names of modules created with `<CREATE >`. #### Shortcuts to just include prior modules (say, you want the prior modules, a `<focus>`, and then new content), you can use: <modules prior="SHOW" otherAttribues="whatever" /> if you just want to specify one module, you can use the following: <modules value="moduleName" otherAttributes="xxx" /> Actually, you can use `value=".."` and list of modules -- the two will be concatenated (first the `value=..` modules, and then the list of modules. If you only are specifying a module in a `content`, you can use <content module="moduleName" otherAttributes="xxx" /> Note that `modules`, etc. can still be specified: the `module=` moduleName will be displayed first.

Event actions
The dSurvey XHTML extensions, and SPEC files, work with several kinds of "events". Essentially, an event is something that causes the browser to take some kind of action -- such as displaying a new group. These events are:

1. the group is loaded: content displayed, equations called, etc. (`<exec>`).
2. the participant hits a
   (`<button>`),
3. a timer has hit zero (`<timer>`),
4. the server supplies a status variable (`<query>` and `<notify>`).

For each group, the SPEC file is used to specify which of these several kinds of events are activiated. When activating an event, you can customize several features (such as descriptive text). More importantly, you must specify what actions are to be taken when the event occurs -- when a button is pushed, when a timer hits zero, or when the server responds.

In particular, you can specify a variety of event actions: | functions can be run (<`call>`) the next group (in this section) can be displayed (<`next>`) an explicitily specified group, or section, can be displayed (`<goto>`) results can be submitted to the server (`<submit>`) display a page in a new, popup, window (`<popup>`) XHTML elements on the current page can be hidden or displayed (`<display>`) modify results on current page (`<update>`) recover prior round results (from the server) (`<recoverPrior>`) send an email (`<email>`)
... | Moreover, <`if>` statements can be used to make these actions conditional -- so that what is done can depend on the value of session variables and on the server's status variables!

The general syntax of an `exec`, `button`, `timer`, or `query` event is:

<events> <exec> or <query> or <button> or <timer> <id value="anId" /> (used in button and timer) <text otherAttributes="xxx" var="varname" > text string </text> (used in button) <time value="nseconds" repeat="ndo" /> (used in timer and query) <serverVar value="serverVarname" desc="descriptive_word" saveVar="varname" /> (used in query) <timerDisplay> <at time="nsec" bysec="rate" class="aclass" style="astyle" /> </timerDisplay> <call> equations </call> <submit saveOnly="1" id="anid" var="avar" /> <message long="message to display while submitting" short="status_word_sent_to_server" /> <save > nameVar = survey_global_var </save > </submit > <recoverPrior toModule="aModule" modules="modList" download="0/1" /> <popup modules="modList" url="aURL" target="aWindow" noProcess="1" retain="1" > <title>Window title </title> <attributes> Window attributes </attributes> </popup > <display how="howDisplay" style="a_cssStyle"> list of ids </display > <update id="awindow.anid" toModule="moduleName" noProcess="1" append="1" modules="module list" > xhtml content </update > <goto group="agroup" section="asection" /> <next /> <stop /> <break /> <if value="logical equation" > call, submit, next, break, stop, goto ... </if> </query> or </button> or </timer> or </exec> </events>
The following details the options. Note that

- `<id>`, `<text>`, `<time>`, `<timerDisplay>`, and `<severVar>` are event specifications. They can be anywhere (their ordering does not matter).
- `if, submit, display, update, recoverPrior, display, popup, call, break, stop, next` and `goto` event actions are used the same way in in all four events -- so they are described in a seperate table.

EXEC
`EXEC` is basically an initialization event. If a `<exec>` is specified, then all its event actions will be processed as soon as the group is fully loaded. Thus, `exec` event-actions are always processed, but are only processed once. `exec` can can be a useful way of jumping to an appropriate section or group, depending on the current values of parameters. `<exec>` is processed before any other event (i.e.; before a `<query>`). Thus, if an `<exec>` causes transfer of control to another group or section (say, through a `<goto>`), then the other events will not be processed. `There is one exception to this rule:` <notify> specified outside of <events> Notes: there are other ways of performing actions when a group is loaded (say, by using a <call >) -- but these can not be easily used to jump to a new section or group. `<exec>` (like all the other `events`) is processed after a group's modules are displayed. Thus,values of variables set in an `<exec>` will not be used by any `<call>` or `<set>` associated with this group Example <exec> <call> smessage='SUBMIT_INTRO' $+ nowround </call> <submit saveOnly="0" var="sub1" > <message long="Submitting intro round results to server" varshort="smessage" /> <save> <include sub="SAVE_VAR1" /> QTEST_answer[*] </save> </submit> <call> writeAlert('Results submitted for ' $+ nowRound,5) </call> </exec>

BUTTON
<button busy="waitSeconds" if="logicalCondition" focus="1" repeat="ndo" message="a message" > <id value="anId" /> <text otherAttributes="xxx" var="varname" > text string </text> event actions... </button>
`busy="waitSeconds"` | `busy` is optional. It specifies what to do if an earlier event is still active. `waitSeconds` is the number of seconds to wait before trying again -- before checking to see if the earlier event has finished (and has not caused a new group to be loaded). Special value: if `busy="0"` is used-- give up. Note that if `busy` is not specified, `busy="2"` is used.
`if="logicalCondition"` | `if` is optional. If specified, it controls whether or not this event is enabled. Basically, if the logicalCondition evaluates to true, the button is created. Otherwise, it is skipped (and no button is created). Note that an `if` used as an attribute (of `button`) controls whether the button is enabled. In contrast, an `<if>` used as an element (between a `<button>` and its matching `</button>`) controls whether event-actions are processed after the button is pressed.
`message="a message"` | `message="a message"` is optional. If specified, when the button is clicked the button's text will be changed to this message (using a light font on a light background). If not specified, `please wait` is used. If you specify `message="0"`, then the button's text will not be changed.
`focus="1"` | `focus="1"` is optional. If specified, this button will recieve the focus -- the participant won't have to move the mouse on top of the button. Notes: you can also set the focus using the <focus /> option under `<group>`, or setting a class="FOCUS" attribute in a `DIV`, `SPAN`, or `INPUT`. `focus="1"` takes precedence over `<focus />` If a `focus="1"` (in a `button`) and a `class="FOCUS"` (in a `DIV` or other element) are both specified, the first occuring one will be get the focus.
`repeat="ndo"` | `repeat` is optional. If specified, `ndo` should be the number of times the button can be pushed. If not specified, the button can be pushed an unlimited number of times. After the button has been pushed `ndo` times, it will ignored (button pushes will cause nothing to happen). Note that `repeat="1"` means only the first button push is used. `ndo` can be a number, a session variable, or an element name (whose value will be used).
`<id value="anid" >` | Optional. `anId` is the ID of the div (or span) to write the button into. If `id` is not specified, the `_headerButton` "absolute" area is used. This is an absolute div that stays in the same position even when the browser is scrolled up and down.
`<text otherAttributes="xxx" var="varname" > text string </text>` | `text string` is the string to display in the button. If not specified, `Submit` is displayed. `var="varname"` is optional. If it is used, and `text string` is not used, the value stored in the `varname` variable will be used. Note that you can use `@varname` to use the value of an XHTML element. `otherAttributes` can be any other attribute, such as `style` or `class`. Hint:`class="styleButtonUnderline"` will create an underlined url style clickable-link.

TIMER
<timer busy="waitSeconds" if="logicalCondition" > <id value="anId" /> <time value="nseconds" repeat="ndo" /> <timerDisplay> <at time="nsec" bysec="rate" class="aclass" style="astyle" /> </timerDisplay> event actions ... </timer>
`busy="waitSeconds"` | `busy` is optional. It specifies what to do if an earlier event is still active. `waitSeconds` is the number of seconds to wait before trying again -- before checking to see if the earlier event has finished (and has not caused a new group to be loaded). Special value: if `busy="0"` is used-- give up. Note that if `busy` is not specified, `busy="2"` is used.
`if="logicalCondition"` | `if` is optional. If specified, it controls whether or not this event is enabled. Basically, if the logicalCondition evaluates to true, the timer is created. Otherwise, it is skipped (and no timer is created). Note that an `if` used as an attribute (of `timer`) controls whether the timer is created. In contrast, an `<if>` used as an element (between a `<timer>` and its matching `</timer>`) controls whether event-actions are processed after the timer expires.
`<id value="anid" >` | Optional. `anId` is the ID of the div (or span) to write the timer into. If `id` is not specified, the `_headerTimer` area (top of the screen, 125 pixels from right) is used.
`<time value="nseconds" repeat="ndo" />` | `nseconds` is a number of seconds this timer will last. When the timer hits 0, the event occurs. `ndo` is the number of times repeat the countdown timer. If not specified, or `repeat=""`, then run the countdown timer just once. Note that after the event occurs (the timer hits 0), its event actions are done. If these event actions includes a valid `stop`, `next` or `goto`, the repeat will not happen. `ndo` and `nseconds` can be a number, a session variable, or an element name (whose value will be used).
`<timerDisplay > <at .... /> </timerDisplay >` | `timerDisplay`, and `at` are optional. They are used to change how the count down timer is displayed. For the details, see below.

QUERY
<query busy="waitSeconds" if="logicalCondition" saveVar="varname" toGroup="serverVar" > <time value="nseconds" repeat="ndo" /> <servervar value="serverVarname" descVar="varname" desc="descriptive_word" stateVar="sVarname" /> event actions... </query>
Notes: | <notify> is a simple version of `<query>` Several options of `query` are designed to work with the checkClients SPEC file action.
`busy="waitSeconds"` | `busy` is optional. It specifies what to do if an earlier event is still active. `waitSeconds` is the number of seconds to wait before trying again -- before checking to see if the earlier event has finished (and has not caused a new group to be loaded). Special value: if `busy="0"` is used-- give up. And do not send another query. Note that if `busy` is not specified, `busy="2"` is used.
`if="logicalCondition"` | `if` is optional. If specified, it controls whether or not this event is enabled. Basically, if the logicalCondition evaluates to true, the query is created. Otherwise, it is skipped (and no query is created). Note that an `if` used as an attribute (of `query`) controls whether the query is created. In contrast, an `<if>` used as an element (between a `<query>` and its matching `</query>`) controls whether event-actions are processed after the query recieves a response from the server.
`saveVar="varname"` | `saveVar` is optional. If specified, the response from the server will be saved to the `varname` variable. If `saveVar` is not specified, the `_queryResponse` variable name is used. Note that any prior value of the `saveVar` will be overwritten,
`toGroup="serverVar"` | `toGroup` is an optional shortcut. If specified, the response from the server is used to indicate which group (by number) to display next.
`<time value="nseconds" repeat="ndo" />` | `nseconds` is the time to wait before querying the server. After the query, the event occurs upon reciept of a response from the server. `ndo` is the number of times to repeat this query. If an event action does not include a valid `stop`, `next` or `goto`, the browser can re-query the server. After `ndo` attempts, the browser stops querying. If not specified, or if `repeat=""` is used: an infinite number of queries will be done. `ndo` and `nseconds` can be a number, a session variable, or an element name (whose value will be used).
- `<serverVar value="serverVarname" descVar="varname" desc="descriptive_word" stateVar="sVarname" />` Note: you can use `<var ... >` as a synonym for `<serverVar ... >` | `value="serverVarname"` `serverVarname` is the name of the variable, on the server, to be queried. Its current value will be downloaded from the server, and then saved to the `_queryResponse` (or to the `saveVar="varname"`) variable. `desc="descriptive_word"` or `descVar="varname`. Optional-- use neither, or just one of, them. `desccriptive_word` should be a one-word descriptive phrase. `varname` should be the name of a variable that contains a one-word descriptive phrase. `stateVar="sVarname"`. Optional. `sVarname` is the name of a variable that contains a one-word descriptive phrase. As described below: in contrast to `desc` (or `descvar`), `stateVar` is a global, semi-permanent variable -- if you do not specify it, the most recent value of `stateVar` is used.
  Notes: |
if `descVar` is specified, `desc` is ignored. the value of the `descVar="varname"`, and `stateVar="sVarname"`, variables are those current the the time of a `query`. Thus, their values can be changed on-the-fly; say, using a `<call>` in a `<button>` or an `<exec>` event preceeding the `<query>`. Values specified in `desc` (or `descVar`), and in `state`, are stored in the current status of participants server database. `stateVar` will set the `_queryState` global variable. The value of `_queryState` is sent to the server on every `query` (or `notify`). Thus, if you do not specify a `stateVar` in a given `<query>`, the most recently specified value will be used. The idea is that the `stateVar` doesn't change very often (say, just at the beginning of a round), while the `desc` is specific to each `query`. Note that the default value of `_queryState` is `0`. The UserStatus task in control panels will display the latest value of a `desc` (or a `descVar`). The <checkClients> control-panel action uses both the `desc` (or `descVar`) value, and the `state` value: `desc` (or `descVar`) is used as the `message` variable `state` is used as the `state` variable

#### Special cases

Instead of querying the server for a value, `query` can be used to query the current value of a session variable, or of an XHTML element. To do this:
- To query a session variable, use `%serverVar`. That is, put a `%` before the variable name.
- To query an element's value, use `@serverVar`. That is, put a `@` before the variable name.
The main purpose of using either of these is to institute a loop -- you can monitor the value (of a session variable or an element), checking every `nseconds` seconds. Note that this is somewhat different than exec, which only runs just after the group is loaded.

NOTIFY -- a short version of QUERY
<notify var="aVarName" value="a_oneWord_message" repeat="YES" stateVar="sVarname" />
`<notify>` is used, when the group starts, to send short messages to the server. These message will be saved in the current status of participants server database, and may be used by the <checkClients> feature in a control panel. Basically, `<notify>` is a shorthand for a `<query>` that ... only sends one request (`repeat="1"`) does not care about what the value of a server variable is has no event actions
Special feature | `<notify>` can be used outside of `<events>` -- say, as the first element after the `<group>`. There is one substanative difference between specifying `<notify>` inside of vs. outside of `<events>` inside of `<events>` : the `<notify>` will be processed after an `<exec>`. Thus, if the `<exec>` transfers control to a new section (or group), the `<notify>` will not be processed. outside of `<events>` : the `<notify>` will be processed before any other events (including any `<exec>`). Thus, even if the `<exec>` transfers control to a new section (or group), the `<notify>` will be processed.
`var="aVarname"` | `aVarName`, if specified, is a variable that contains the short message to send to the server (`var` is equivalent to `descVar` in a `query`).``
`val="a_oneWord_message"` | `a_oneWordMessage`, if specified, is a short (one word) message to send to the server (`val` is equivalent to `desc` in a `query`).``
`stateVar="sVarname"` | `sVarName`, if specified, is a variable that contains a short message to send to the server (`stateVar` is equivalent to `stateVar` in a `query`).``

`repeat="YES"` Optional. By default, as soon as the contents of the group are displayed,`<notify>` will post a single query to the server (that contains the message).
If `repeat="YES"` is specified, then this query will occur every 5 seconds (until the group is left).
Typically, `repeat="YES"` is used with `aVarName` that may be changed (say, by the participant).
If both `var` and `value` are specified, the `var` is used (the current value of `aVarName` is used as the message).

Event actions
`<break>, <call>, <display>, <goto>, <next>, <popup>, <recoverPrior>, <email>, <stop>. <submit>,` and `<update>`, are event actions. They specify what to do when the event occurs ... say, when a button is clicked, a timer expires, or a the server responds. <if> is used to control whether event actions are considered. You can specify any mixture of these event actions, and you can specify none, one, or many `if`. Note that ordering does matter (unlike the event specifications, where ordering does not matter).
<break /> | Similar to `stop`. Stop processing this event. When a `<break>` is encountered, no more of the event-actions associated with this event will be processed. However, this event can be re-enabled. This means that `query` and `timer` can repeat. Note that `<break>` is often used inside of an `<if>` (so that processing can be conditionally stoppped).
<call> equations </call> | You can specify one, or several, equations to evaluate. These equations can call functions. Example: `didSubmit=1` To call more than one equation, put each equation on a seperate line. The `<equations>` are processed in the order of appearance. You can use `<if ... >` to control which equations, inside of a `<call>`, should be processed. Reminder: to use the value of a variable returned by a `query` -- say, to use for comparison purposes on the next `query`. use the variable specified in a `saveVar` attribute in `<query>` (if you did not specify `saveVar`, the response to the most recent query will be in the `_queryResponse` session variable). You can review the order that equations are processed.
<display how="howDisplay" style="a_cssStyle" > list of ids </display > | Display, or hide, one or more HTML elements. `Display` is used to hide, or display, HTML elements on the current page. This will not change content on the page, but it will make text, etc appear and disappear. In particular, `<display>` is typically used to hide, or display, `<div >` and `<span >` elements -- that is, the stuff between a `<div >` and a `</div >`, or between a `<span >` and a `</span >` Details:; `list of ids`: A space-delimited list of the `id`s of elements, on the currently displayed page, you want to display/hide. If there is no such `id` on the current page, an error message will be displayed. `how="howDisplay"`. Optional. If used, `howDisplay` should be one of: `block`: display as a DIV (start on a new line) `inline`: display as a SPAN (do not start on a new line) `none`: do not display `0` (or not specified): toggle between `none` and . That is, hide it if the element is currently visible, but display the element if it is currently hidden. `style="a_cssStyle"`. Optional. If used, the css style of the element(s) will be changed to `a_cssStyle`. That is, any css style associated with the element(s) will be overwritten! Hint: do not include `display` or `visibility` options in `a_cssStyle`. Note: `update` can be used instead of `display` to update what is displayed on the browser (without invoking a new group or section). `update` is more powerful, since you can change the actual elements on the page, rather then merely changing the visiblity and style of currently existing elements. But sometimes having more power is not as important as ease of coding!
<goto section="asection" group="agroup" /> | Go to a specific group in the current section,the first group in a different section, or a specific group in a specific section. If you specify both a `section` and a `group`, the specified group in the specified section is displayed If you only specify a `section`: the first group in the specified section is displayed If you only specify a `group`: the specifed group in the current section is displayed If you do not specify a `group` or a `group`: the next group in the current section is displayed You can refer to the groups & sections by name, or by number. If you use a name, it must exist: a group, or section, with this name must be available. If no such group, or section, is available an error occurs. Group numbers: the number refers to the group within the section after using `<IF>` to remove groups. That is, the number does not refer to where the `<GROUP>` appears in the SPEC file (though, if there are no `<IF>` used, it will!). If a number > the number of available groups (in this section) is used, or if a non-existent group name is used, an error occurs. #### Special Case To repeat the current section (from the first group), you can use `<goto section="." />` To repeat the current group in the current section, you can use `<goto section="." group="." />` #### Shortcut Instead of `section="secname" group="grpname"`, you can use `group="secname.grpname"`. If you use this dotted name, it will override a section-name specified in a `section="secName"`
<next /> | Jump to the next group in this section. If currently displaying the last group in the section, do nothing. Basically,`<next />` is a synonym for `<goto />`
<popup modules="modList" url="aURL target="aWindow" noProcess="1" retain="1" > <title> ... </title> <attributes> ... </attributes> </popup > | Display one, or several, modules in a new, popup, window. `popup` is a convenient tool for displaying information in a popup window, say when a participant hits a help button. The contents of this popup window is built using `modules`. You can't do all of the same tricks possible when defining a `<group>`, but the contents of these modules will be processed for special tagnames, <attributes> and the `SET`, `KEEP`, and `INFOLINKS` secondary features. Note: events can not be associated with this window (that is, you can not include event buttons in the new popup window). #### Details `modules`: A list of modules to use. The contents of these modules will be displayed. `modList` should be a space delimited list of module names. If one of the module name does not exist, an error occurs. `url`: `url` is used only if `modules` is not specified. `aURL` should be any URL (fully qualified or relative). The URL will be loaded into the window, without any processing (i.e.; `special tagnames` are not processed). `target`: Optional. The name of the window to write contents to. If no `target` is specified, a window named `viewer` will be used. Special case: If `target="self"` is used, the current (main) window will be used. In this case, no more events will be processed (currently active events will be ignored). Therefore, use this carefully! `retain`: Optional. If `retain="1"` is specified, the window will not be closed when a new group is loaded. Otherise, the window will be closed when a new group is loaded. `noProcess`: Optional. If `noProcess="1"` is specified, the contents of the modules will not be processed for `special tagnames`, etc. This is used to speed up processing time when you know there is no need to dynamically update a module (say, if the module was created by UPDATE). Note: be careful when using `noprocess="1"` with modules created using update -- if you do not use `noprocess="1"`, you may update elements you did not want to update (that is, elements whose value should be resolved when the `update` was processed, rather than when the `popup` is processed). `<title>`: Optional. The title to use in the window. Example:`<title>Personal help window </title>` `<attributes>`: Optional. Attributes to use when opening the window. This should be a string of attributes used in the javascript `window.open('',url,attributes)` function. If not specified, the following is used (to open a window with minimal navigation and toolbars): `<attributes>toolbar=0,location=0,directories=0,status=0,toolbar=0 </attributes>` Note on style-sheets: Two style sheets are associated with the newly created popup windows: `/dsurvey/lib/svylibE2.css`: some general purpose styles (you might find some of them useful) `/dsurvey/instruments/INSTNAME/lib/myStyles.css` : CSS file created specificallly for this instrument -- where `INSTNAME` should be replaced by the name of the instrument.
<recoverPrior download="0" toModule="amodule" modules="modlist" /> | Recover, from the server, the history archive, use it to repopulate the priorRound database, and then save a history page to `amodule` using `modlist`. Note that the <recover> option of <init> is a slightly deprecated alternative to `<recoverPrior>`.
Syntax: | `download="0"` : optional. If not specified, `recoverPrior` will download (from the server) the `history archive`. If you specify `download="0"`, the history archive will not be downloaded, hence the prior variables will not be modified. `toModule="amodule"`:optional. A module that is used to store the history page. You can then use this module elsewhere: say, you can use it in popup or update. `modules="modlist"`:optional. Modules to use to create `amodule`. Note that if either `toModule` or `modules` is not specified, then a history page will not be created.
`recoverPrior` is primarily meant to be used if/when a participant reloads his browser. When that happens, any priorRound results (that are stored by the browser) will be erased. `recoverPrior` simplifies recovery of this information from the server. Furthermore, you can also then recreate a history page (a HTML containing page that shows the particpant what happened in prior rounds) which can then be displayed (say, in a popup when a button is hit). To use `recoverPrior` you must maintain a `history` server archive. This is done by specifying <uploadData type="HISTORY" > in your `control-panel`. This `uploadData` should be specified at the end of every round (say, just after results have been computed for a round). In other words: if you don't use `uploadData`, `recoverPrior` will not work!. Combining `uploadData` and `recoverPrior` allows you to create complex history pages. However, it does require a fair amount of setup (i.e.; you have to specify the module used to create a round's history). If you are willing to settle for less customization, you may want to create a simple History instead! For details on using `recoverPrior` and `uploadData`, see Appendix 11.
<email var="statusVar" > <to>recipient </to> <from> sender </from> <subject>subject </subject> <message> text </message> </email> | Send an email
- Syntax: | `var="statusVar"` : Optional. `statusVar` should be the name of a dSurvey variable. The status of the email is recorded here. If you do not specify a `var="statusVar"`, this status is recorded in the `EMAIL_STATUS` variable. You can access this variable just like any other dSurvey variable. For example, with `<show var="EMAIL_STATUS" />` if the email succeeded, the status always starts with `ok`, while if there was a problem it starts with a minus sign (a `-`). You can use something like the following to display a status report (say, in the next `SECTION`). <set> tmp=getWord(email_status,1) </set> <if value="tmp eq 'ok' "> An e-mail listing your decision has been sent to your address (<show var="myContact" />) </if> <if value="tmp ne 'ok' "> Sorry, we were unable to send you (<show var="myContact" />) an e-mail listing your decision. <br />(Error reported: <show var="EMAIL_STATUS" />) </if> `<to>recipient</to>` : the email address of the recipient of the email. For example: `joe@myhome.org`. You can specify multiple recipients by using a space delimited list of email addresses. Alternative: `<to var="avar" /> :` Use the contents of the `avar` as the recipient's email address(es). For example, `<to var="mycontact" />` will use the `contact` variable the participant supplied when he joined the session (assuming that GET_CONTACT was enabled in the session descriptor file). `<from>sender</from>` : The address of the sender. Alternative: `<from var="avar" />` : Use the contents of the `avar` as the sender's email address. This is used as an optional header -- it complements the `DEFAULT_FROM` variable set when dSurvey is installed. `<subject> Subject line </subject>` : The subject (used as an email header). It can not be more than 100 characters `<message> The email message </message>` : The email message (it can be multiple lines). This message will be sent as is (without processing variables) Alternative: `<message module="modnamer" />` : Use the contents of the `modname` module. This module will be processed (just like a `<content>` modules), and the result will be used as the message. This allows you to include variables in the body of the message (such as the recipient's name, and values selected or computed). You can use `<show>` in your module to display current (participant specific) variables. However, if you want to send a plain-text email, you should include a `nospan="1"` attribute in `<show>`. Example: `<show var="myName" noSpan="1" />`. If you do not include this `noSpan="1"`, then `<span>` `</span>` will appear in the email (surrounding the value you wish to include). Example (assuming `myName="Robert"`)
  The `<show>` | What appears in the email
  --- | ---
| Hello <show var="myName" /> ! | Hello <span>Robert</span>!
Hello <show var="myName" nospan="1" /> ! | Hello Robert!

#### Setup note

In order for the `<email>` event action to work, several site-specific dSurvey SMTP parameters must be properly set. See setEmailParams.htm for details.
<stop />
Stop processing this event. When a `<stop>` is encountered, no more of the event-actions associated with this event will be processed.

Furthermore, this event will not be re-enabled. This means that `query` and `timer` will not repeat.

Note that `<stop>` is often used inside of an `<if>` (so that processing can be conditionally stoppped).

However, other events are still enabled. In other words, `stop` is used to cease paying attention to one, out of possibly several, events associated with a group.

<submit
saveOnly="1" noConfirm="1" round="roundVar" otherAttributes > <message ... /> <save> ... </save> </submit>
Submit information to the server. Three sources are used to compile a list of variables, and their values, to submit to the server.

1. A special element (such as <value>, <radio>, and <checkbox>) with a `<submitName>` child element (this is a little bit deprecated)
2. Variable specified using a `<save ... >` in this `submit`.
   If you want to use the build a data dictionary utility, all `submit` variables should be specified using this method!
3. Somewhat deprecated... All XHTML elements (other than the above special elements) in the current group that have a a `submitName` attribute. The value of this `submitName` attribute is used as a variable name, and the elements value is used as the value.
   Typically, this `submitName` method is used with simple `input` and `textarea` elements.

   Special trick: when the `submitName` includes a # character, the # is replaced by the `IDX` attribute of this element.
   For example, ...

   <input type="hidden" class="SUBMIT" submitName="COST#" idx="3" value="100" />
   will yield a variable name (submitted to the server) of `COST3` with a value of `100`.

Note that the list of variables to submit can be accumulated by using the `saveOnly="1"` attribute. Thus, you can accumulate values set across several groups, and at the appropriate time submit all the values using one server request.

#### Major details...

- `<message >` and `<save >` must be child elements of a `<submit >`
- For a complete list of the options supported by `<submit>`, see Appendix 9.

<Submit> attributes...
- saveOnly="1" Nothing will be submitted to the server. Instead, as specified above, information specified by the client will be stored for later use.

  How is `saveOnly` used? One can have several `submit` events, each associated with a different page of questions, and each with a `saveOnly="1"` attribute. Finally, you would use a `submit` element without `saveOnly="1"` -- this would actually submit information to the server, including information retained by these prior (`saveonly="1"`) `submits`.

- noConfirm="1" Optional. If specified, than the `confirm` feature of the <radio> special tagname will be suppressed. This is useful if you want to force a submit (say, due to a `<query>`), regardless of whether a required `<radio>` has been chosen.
- round="roundVar" Optional. A value, or a variable name, specifying what round this is.
  If not specified, the value of the `nowRound` variable is used.

  Note: failure to specify a valid `roundVar` (either explicitily or using the `nowRound` default) may lead to the server not saving the submitted variables (say, if the `reSubmit` session-descriptor variable is set to 0).
- other attributes include: `toCurrent="1"`, `notFinal="1"`, `ct="n"`, `messageId="divd"`, and `var="varname"`.
<message> attributes...
- long="a message" When values are submitted to the server, the `a message` is displayed on the particpant's browser). This message disappears after the response has been successfully recieved by the server. Note that if the server fails to acknowledge reciept of the submitted information, an error occurs.
- short="one_word_status_message" Optional. A one word status message that the server can use to track each client's current status.
- other attributes include: `varLong="aVarname"`, and `varShort="aVarname">`
`<save > variables-to-save-definitions </save>`
Optional. You can specify extra variables to submit to the server using `save`. If specified, variables-to-save-definitions should be a mutli-line string.
Each line will contain a simple equality of the form: `submitVar=a_variable`, where...
- `submitVar` : a variable name to submit to the server
- `a_variable`: value to submit to the server (using `submitVar` as the name).
  `a_variable` can be a number, a ' quoted string', a session variable or session array element, or the value of an XHTML element (prefaced with a @).
  It can not refer to an attribute's value (that is, it can not be `#attname`). And it can not be an equation.
Alternate:`var submitVar=a_variable` -- if you precede an equation with a `var`, then instead of submitting `submitVar` to the server, a dSurvey session variable will be created. Appendix 9 details a number of shortcuts, and contains an example.

#### Notes...

- You can not have more than one `<submit>` per event-action.
- Once a `submit` without a `saveOnly="1"` occurs, the list of stored for future submission variables is removed. Thus, you can use `saveOnly="1"` to accumulate variables to submit, but once you actually submit these "accumulated" variables, they will be discarded.

<update id="awindow.divID" toModule="modName" modules="modList" noProcess="1" append="1" > xhtml content </update >
`update` is used for on-the-fly updating of your current display, or of a module. It works by changing the contents of selected elements (such as `div` or `span` elements). This update is dynamic: the content to be updated will be processed for special tagnames, <attributes> and the `SET`, `KEEP`, and `INFOLINKS` secondary features.

In contrast:`display` can also be used to change the current display, but it will only change the visibility and style of existing elements. That is, `display` is not as powerful.

#### Details

- `id="divID"` or `id="awindow.divid"`: the `id` of the element to update (the target element).
  If `awindow.` is not specified, the element with an `id` of `divID` in the current section (in the main window) will be modified.
  If `awindow` is used, `awindow` must specify a window name opened using an popup.

  Typically, the specified element (i.e.; with an `id` of `divID`) this will be a `div` or a `span`.

- `toModule="modName"`: If `toModule` is used, instead of updating an element in the current section (on the client's main window), or in a popup window, the contents of the `divId` in the `modName` module will be updated. Later, you can write this module somewhere, perhaps after several successive updates.

  If `id` is not specified, the contents of the module will be replaced (or appended to). id is not specified, and `modeName` does not exist, the module will be created.

  Special usage: You can specify an indexed module using a syntax of
  `toModule="aModeName[varname]"` where `varname` can be a number, or a session variable (including prior session variables).

- `modules="modlist"` `modList` is optional. If specified, it should be a space delimited list of one or more module names.
- `append="1"`: Optional. If `append="1"` is specified, content (either from modules or the xhtml-content) will be appended to the current contents of the target element. If not specified, the content will replace the current contents of the target element.
- `noProcess`: Optional. If `noProcess="1"` is specified, the contents of the modules (or the XHTML content) will not be processed for `special tagnames`, etc.
  This is used to speed up processing time when you know there is no need to dynamically update.
- `xhtml content`: Optional, ignored if `modules` is specified. Any legal xhtml content can be specified. If `modules` is not specified, this `xhtml content` will be used.

As noted above, before writing to the target element, the updated content (whether retrieved from a `moduleList` or from the `xhtml content`) will be processed for `special tagnames`, etc.

In fact, you can combine xhtml content with modules by using `insert`.

Example ...
<update id="someid"> <b> My module is: </b> <insert module="myMod1" /> <br /> Good bye. </update>

#### Notes:

- Caution: modules inserted using a `insert` (such as `myMod1` above) will not be processed for `insert`. In contrast, modules specified in a `moduleList` will have `insert` processed.
- When specifying the `id`, case matters. However, if you specify a window (i.e.; `helpWindow.latest`), the window name is case InSensitive.
- If the window was never opened (say, a button that opens the desired window was not clicked), then a short message is written to the status box (at the bottom of the main window). That is, nothing is written (since there is no place to write it to).
- If the specified `toModule` does not exist, an error occurs.
- If the specified id does not exist (either in the main window, a popup, or a module), an error occurs.

  Hint: if you are building a module (say, adding information after each round), to avoid startup problems (say, when a participant hits a link before the first round is over) you might need to initialize. This can be done using something like the following, in the first group & section of your SPEC file.
  <exec> <update toModule="module_to_use" noprocess="1" > </update> </exec>
- If you use `toModule` to update a module, the INFOLINKS secondary feature can not be processed -- an alert with an error message will appear.

<if value="logical equation" > | <call> <next> <goto> <submit> etc.
| Controls whether embedded event actions are considered. If the logical equation evaluates to true, then the event actions within this `<if> ... </if>` is considered. Otherwise, they are ignored.

Shortcuts: Several shortcuts, that simplify several commonly used events, are also supported... see below for the details.

Examples | <events> <exec> <if value="myVersion==2" > <goto section="SHOWV2" /> </if > </goto section="SHOWV1" /> </exec> </events> <events> <button> <text> next group </text> <next /> </button> <query> <var value="intro_step" desc="intro1" saveVar="iStep" /> <if value="(_groupNumber+1) lt iStep" > <next /> </if> <update id="statusBox" > XHTML content for statusbox </update> <update id="statusBoxLarge" modules="HelpAlert1" /> </query> </events> <events> <exec> <popup modules="help1 help2" target="viewHelp" > <title> The Help Window </title> </popup> </exec> <timer> <id value="tBlock" /> <time value="45" repeat="100" /> <goto section="incomeQuestions" /> </timer> </events> <events> <timer> <id value="tBlock" /> <time value="45" repeat="100" /> <submit > <message long="Saving whatever your current answers are" short="answers_timeout" /> </submit > </timer> <button> <text> Submit you answers </text> <submit > <message long="Saving current answers " short="answers_button" /> <save > myEarnings=earnings{1] myColor=color2 < /save > </submit > </button> </events>

#### How does it work?

- Events are enabled -- they wait for an event (the group is loaded, a button push, a timer expiring, or a response from a server query).
  Events can be conditional -- if they have an `if` attribute that evaluates to false, they will not be enabled.
- When an event occurs, the event actions (`<call>, <submit>, <stop>, <break> <goto>`, and `<next>`) are processed in order of appearance.
- if a `<stop>` or `<break>` is processed, all following event actions are ignored.
- if a `<next>` or `<goto>` is processed, all following event actions are ignored -- since these cause a new group to be displayed!
  Exception: when `<next />` is encountered, and the last group is being displayed. In that case, the `<next />` is ignored (and the next event action is processed).
- If an `if` is specified, its logical equations is evaluated. If it evaluates to `false`, the embedded event actions are ignored. Otherwise, they are processed (in order of appearance).
- `<goto>, <stop>, <break>` and `<next>` that are not inside of an `<if> ... </if>` should always be at the end (since any following event actions won't be processed).
- A `<call>` inside of an `<if>` may have one or more embedded `<if>` statements.
- If no `<next>` or `<goto>` is processed, the current group is not changed -- which means the display is not changed.
- Thus, if the `goto` or `next` is used inde of an `<if>` -- the group is changed only if the `if` is true.

#### Notes on countdown timers: using <timerDisplay> <at .. > </timerDisplay>

If `<timerDisplay>` and `<at>` are not specified for a countdown timer, a default formatting is used:
- While the remaining time is > 15 seconds: a small font is used, that changes every 5 seconds
- When the remaining time is between 5 and 15 seconds, a larger font is used, that changes every second
- When the remaining time is < 5 seconds, an even larger red font is used, that changes every second
You can use the `<timerDisplay>` and `<at>` to change this pattern. Basically, every second the browser will examine all the specified `<at>`.

- The `nsec` (from `time="nsec"` is compared to the remaining time. If it is less than or equal to the remaining time, this `<at>` is chosen. If not, the next `<at>` is examined.

  Therefore: the `nsec` values should be increasing (the first `<at>` in the `<timerDisplay>` file should have the smallest value of `nsec`).

- The `bysec` attribute is read from this chosen `<at>`. The count down timer will be updated every `rate` seconds. If `bysec` is not specified, `5` is used.
- You can set a `class` and/or a `style`. They will be used as attributes for the div that contains the countdown timer.

Technical notes:

- You can change the default formatting by modifying the `styleUpdateTimer` classes in svylibeE2.css.
- The default can be replicated using the following:
  <timerDisplay> <at time="5" bysec="1" class="styleUpdaterTime1" /> <at time="15" bysec="1" class="styleUpdaterTime2" /> <at time="9999999998" bysec="5" class="styleUpdaterTime3" /> </timerDisplay>

#### Notes on query:

- The `serverVariable` should be a one word variable name. A request will be sent to the server asking for this variable's current value. Typically, the server will return an integer.
  Or ...
- To query a session variable, start with a %. For example: `%MyCost[1]`.
- To query an element's value, by name, start with a @. For example: `@MyBid`.
- Upon recieving a response from the server, the value of the response will be saved to the variable specified in the `saveVar` attribute (if not specified, the `_queryResponse` session variable is used).
- event actions will be processed.
  If no `<next>` or `<goto>` is processed, and if `repeat` has not reached its limit, and if a `stop` is not specified: the server is re-queried for this variable (after a `nseconds` delay).
  Reiterating ... the variable specified by the `saveVar` attribute of `query` (by default, `_queryResponse`) contains the most recent value returned by the server. Note that if there is more than `query` active, and neither has a `saveVar` attribute, the value of `_queryResponse` will be indeterminant (it will contain the value of the most recent response from the server).

  Example:
  <if value=" _queryResponse != nowRound_query" > </if> <if value="_queryResponse gt 4 and _queryResponse lt 6" > <if> <if value="my_sv=10 " > </if>

#### Notes on using IF and logical equations

- If logic is used in three places:
  1. `if` attributes of the event: should this event be enabled.
     Example...
     <button if="thisVer==1" > .... </button>
  2. `<if >` as an event-action: should these event-actions be processed
     Example...
     <button > <if value="round lt 10" > event actions </if > </button>
  3. `<if>` inside of a `call` event-action: should these equations & functions be computed
     Example...
     <button > < call > <if value="myCost gt 100 10" > equations & functions </if > < /call > </button>
- You can refer to the current section name by using `_sectionName`.
  You can refer to the current section number by using `_sectionNumber`.
  You can refer to the current group number (in this section) by using `_groupNumber`.
  You can refer to the current group name (in this section) by using `_groupName` (note that the group name can be empty).
  For example, you can compare the `_queryResponse`) to the `_groupNumber`, and advance (say, to the next group) when they are not longer equal.

  Reminder: the group number is display order : it is the order of this group, in this section, after `<if>` has been used to remove groups.

- The logical equation reference session variables, including variables that contain `query` results.

- Hint: to check if a queried variable has not changed (say, you don't want to do anything if it has not changed):
- The first event-action sees if the most recent response is different from a reference variable:
  `<if value="_queryResponse== serverVar_query" > <break /> </if>`
- The last event action sets this reference variable:
  Example: `serverVar_query=_queryResponse`
- Thus: upon getting a changed value from the server: some actions are done and then a reference varialbe (i.e.; `serverVar_query`) is updated. If the value hasn't changed, no actions are done.
- You might want to initialize the reference variable using a `call` in this `group` (that is, a `call` that is not an event action) For an automated substitute to the above, you can use the toGroup shortcut.

  Reminder:: By default, the value of returned from a `query` is stored in a the `_queryResponse` session variable. Or, you can use the `saveVar` attribute to specify where to save the server's repsonse. For example, if
  `<query saveVar="gnext" > <var value="get_next" />`
  then the `gnext` session variable will contain the response to this query.

#### Shortcuts

As a convenience, most of the event specifications can be specified as attributes, rathen than as seperate nodes. In particular....

To specify the ID, REPEAT and TIME of a `timer`: | <timer id="anid" time="nseconds" repeat="nn" > event actions </timer> Sorry, it's too complex to specify `timerDisplay` and `at` as attibutes!
To specify the VAR, DESC, REPEAT, and TIME of a `query`: | <query var="anid" time="nsec" desc="word_desc" repeat="nn"> event actions </query>
To specify the TEXT and ID of a `button`: | <button text="short button text" id="anID" > event actions </button>

Furthermore, you can use some special cases to specify some of the more common types of events.

Using query to move to the next group: | <query toGroup="servervar" /> The `servervar` variable (returned by the server) should point to (by number) the next group to display. Note that `desc` and `time` can optionally be included as attributes. Example: `` <events> <query toGroup="introStep" desc="onStep3" /> </events> In this example... if the current group number is 3, and the server returns `4` when queried for `introStep`, then group 4 will be displayed. Note that if the server returned `3`, nothing will change (since the current group is number 3). Note: the number of a `<group> can change across sessions (say, when an `<if>` is used to suppress a preceding `<group>`).`

Appendices
Appendix 1: Other documentation files
This document will focus on writing SPEC files. You might find it useful to also read the the description of the
XHTML extensions for dSurvey

Or, you can fire up the the dSurvey guide for a complete list of documentation.

Appendix 2: Definitions

Element:
  Element, oftentimes refered to as a XHTML element, refers to a component of an XHTML document. For example, the following chunk of XHTML code:
  <div id="top1" class="c1"> This is the top comment </div> <p /> <h3 > Introduction </h3> We are <em> happy </em> to announce the beginning of our survey! <span name="gogo" class="c1a"> Are you ready? </span>
  contains the following XHTML elements:`div, p, h3, em, span`. Note that the `div` has an `id` attribute of `top1`, and the `span` has a `name` attribute of `gogo`.

Node:
  A node is a web-page-architecture concept. When constructing the stuff to display on the participant's browser screen, a DOM tree ("document object model") is built. This tree is contructed witn `nodes`, where each `node` can connect to a `parent` and zero, one, or more `children`.

  `nodes` can be HTML elements, or they can be modules.
  That is, a module is a DOM sub-tree stored in a node; and this node may be grafted onto a larger tree that contains other nodes that contain other modules.

  Note: this text often mentions `base XHTML element`. This kind of has two synonymous meanings:

  - an XHTML element (say, a `<div>`) that has a number of other XHTML elements contained within its starting and ending tags (say, between a `<div>` and a `</div>`
  - a node that forms a sub-tree.
  Essentially, ther browser proccess `a` into `b`, `b` is then combined with other nodes, and this combination is then displayed on the the participant's browser screen.

Module:
  A block of XHTML code, that can also contain special tagnames (and other features) that are used to make dynamic these modular surveys.
  This HTML code specifies what to display on a participant's browser.
  The special tagnames, etc. permit this display to be dynamic -- to depend on participant specific parameters, to change as the participant enters information, to remember and use information entered in the past, and so forth.

  In other words: | modules can specify content that never changes, or they can specify content that depends on a variety of transient and personallized factors, or they can specify a mixture of the two.

  Modules are specified in files. You can specify several modules in one "modules" file, or you can specify just one module in a file. We will discuss these options below.
Module Group:
  At any given moment, what the participant sees will consist of one, or more, modules. That is, that participant's browser can take several different modules, combine them, and then display them on a single page. This "combination" of modules (which may consist of just one module) is called a module group. As a shorthand, in this document we often just call it a group

  Note that you can think of a "group" as containing all the contents of a single (though perhaps quite long) web page.

  In addition, groups have "javascript functions" associated with them -- you can chose what functions to "execute" when a group is displayed. Note that several useful functions, that support these tools used in dynamic display, can be automatically assigned to all groups.

  Why have modules groups rather then modules?

  1. Using module groups, it is easy to have commonly shared portions of a web page; such as a footer, a header, a set of help links, etc. etc. etc.
  2. You can associate a set of javascript functions with the group -- functions that will be called after the group's modules have been written to the browser. These functions can manipulate the modules contents in numerous ways. In particular, it can update values based on participant specific information.
Module Section:
  A "module section" is a set of "module groups". Groups defined within a section are closely linked. In particular, one often updates the browser's display by replacing one module group with another module group in the same module section.

  More importantly, module sections are the context within which high level control is specified -- where basic steps like "ask for input", "submit input to server", "retrieve new information based on everyone's input", and "display your results" are specified.

  That is, the dividing line between combining groups into a section, or spreading them across several sections, if often dictated by what happens between each "page". If you just want to show a new page, without doing any information processing, displaying a different group within a section is easy. However, if the next page's results depends on extensive processing of information (some of which may need to be freshly retrieved from the server), then displaying a new section may be necessary.

Events:
  After a group is displayed, there has to be some way of informing the browser to display a new group within the current section, or perhaps start a new section. This requires some kind of "event". SPEC files support several types of events:

  Buttons | The participant hits a "submit" button.
  CountDown Timer | A timer expires
  Query | The browser checks the server for the current value of a control parameter. The value of this control parameter, as returned by the server, is used to update which group (or section) is displayed.

  Basically, after displaying a group, and calling any functions associated with this group, the browser will start looking for any of these events. This "looking for" may entail creating a background process; such as a "query the server" loop, or a "timer loop", or "display a button on the screen" page manipulation.

  By using SPEC files, you don't have to worry about the details -- you just have to fall some simple rules (both in the SPEC file and in your modules) and these events will be taken care of.

Event actions:
  When an event occurs (such as a server status variable changing), something has to happen. In particular, a new group should be displayed (and have it's functions run). To determine which group should be displayed, event actions are used.

Functions:
  Modules consists of XHTML code that may contain a number of "attributes". These attributes are used to customize the display, such as by modifying values to reflect participant specific information.

  In addition, javascript functions can be run to modify the display, or to do any other bookkeeping, housekeeping, or other tasks. By default, when you use SPEC files to display groups, as soon as the group's modules are displayed a a number of javascript functions will be called -- these support the dSurvey XHTML extensions. These extensions allow you to manipulate values using a simple syntax implemented using the "custom attributes" included in the XHTML noted above.

  That is: SPEC will call a default set of functions.
    These functions implement these tools -- tools that work together with the attributes (inclued in your XHTML elements in your module files) to make it easy to customize the display!

  Of course, you can also specify your own functions!

Appendix 3: Synposis of XML module files.

XML Module files are XHTML files that specify modules. Typically, you will give them an `.XML` extension. Each module contains valid XHTML (transitional) code, and is contained within a `<module>` and a `</module>`.
Thus, you can have one, or many, modules defined per XML module file.

Would you like to read the details.

Appendix 4: Variables and functions that use them
One of the strengths of this implementation of modular surveys is the ability to save, and use on later pages, variables that contain dynamic information. This information is saved in what are called "session variables", and "session arrays". These variables, and arrays, can be read and used by your javascript functions. More importantly, they can be read by the element modification tools that are such a useful part of the dSurvey toolset.

For example, to read the `myID` variable, you would refer to `myID`. Note that session variables are case insensitive.
See the user's guide for more information on variables (including variables that access element values and attribute values).

A variety of functions are included with dSurvey, or you can code your own functions in a javascript library (and include a link to this file in the <init> section of your SPEC file).

You can see descriptions of the dSurvey functions:

- svyFunctions.htm... generic string manipulation functions, etc.
- svyMath.htm ... some math and matrix functions, mostly used by control panels
- savingResults.htm ... some data object and internal array functions, mostly used by control panels

Appendix 5: Using IF logic
In order to dynamically control what is displayed, SPEC files support `if` statements. For example, these `if` statements are used to select ...

- what equations to evaluate in a `params`
- what `<group>` to include in a `<section>`.
- what `content` is included in a `group`,
- whether to change an elements value, in a `set`
- whether to process event actions

In addition..., the `<if>` special tagname is used (in `modules`) to dynamically control what content will be displayed.

General rules dictate how `if` is used. For example, consider adding content to a group.

SPEC will add (in order of appearance) modules, literal strings, etc. that are specified in `<content>` blocks. However, there may be cases (say, depending on what the participant answered in an earlier section) which dictate exactly what should be displayed. Using `<if>` allows you to satisfy these dictates. In particular these `<if>` work by suppressing addition of a `<content>` to a `<group>`
- If there are no `<if>`s in a `<content>`, the modules, etc. specified in the `<content>` are included.
- If there are `<if>`, and if the logical equation yields a `false`, then the `<content>` is dropped (it is not included in the group).
Reminder: you can specify more than one `content` in a group -- with the items specified in the first `content` displayed before items in the second, etc etc (assuming that this first `content` does not have an `if` that evaluates to false)!

The exact syntax of `if` depends on where it is used (see below for an alternate syntax that can, unless otherwise noted, be used):

- In group and content, `if` controls whether or not a `group` in included in a `section`, of if a `content` is included in a `group` (alternate syntax not supported). Note that ths `<if>` can appear anywhere in the `group` or `content`.
  <if value="logical equation" />
- In events (as an attribute of button, query, or timer), `if` is used to control whether the event is enabled or not (alternate syntax not supported) .
  <button if="logical equation" > event specifications and event actions </button >
- In events (as an element), `if` is used to control which event actions are executed when an event occurs.
  <if value="logical equation" > event actions </if>
- In params and in a calls, `if` is used to control which equations & functions to evaluate:
  <params > ... <if value="logical equation" > equations and functions </if> </params > <calls > ... <call for="whatever" > <if value="logical equation" > equations and functions </if> </calls > </calls >
- In a <set> special tagname `if` is used to control which equations & functions to evaluate:
  <set > ... <if value="logical equation" > equations and functions </if> ... </set >
- A <if> special tagname is used to control what HTML content to display & evaluate.
  Which model? <if value="myModel eq 1" > This is the number 1 model! etc etc </if> <if value="myModel gt 1" > This is NOT the number 1 model, it is model <show var="myModel" /> ! etc etc </if>

In all cases the `logical equation` is an equation that contains logical operators.

- The logical operators are:
  == eq != ne gt lt le ge & and xor | or
- These case-insensitive 2 and 3 letter mnemonics (such as `gt`) must be seperated by spaces.
- You can use ( ) to dictate the order of evaluation. If you do not use (), `and & xor |` and `or` are processed after `== eq != ne gt lt le` and `ge`
- Note that `==` is the same as `eq` , `!=` is the same as `ne` , `&` is the same as `and` , and `|` is the same as `or` .
- Actually, you can specify any math operators, and you can include session variables -- non-zero end results are interpreted as true, 0 is intepreted as false.
- Since it is difficult to use < and > in XML or HTML files, there is no shortcut for `ge le gt` and `lt`.
- The NOT() function may be useful!
- Caution: you can not use attribute values in a logical equation. If you do need to reference a logical operator, create a temporary session variable, and use it inside of the logical equation.

Examples:
<if> value="nowVersion ==1 "/> -- show content if nowVersion equals 1 <if value="round gt 2 and round lt 10 " > </if> <if value="(pet=='dog' or pet=='cat' ) and (isbig==1) "> </if>

#### Special case: checking for undefined variables

You can check to see if a variable has been set. To do this, use the EXIST function.
Example: `<if value=" Exist(newOffer) " />`
-- if the `newOffer` variable has not been specified, this will return `false`.

#### Advanced syntax: using `then` and `else`

When using `<if>` in: `params`, the `<set>` m>special tagnames the `<if>` special tagname, in `events`, and within `call`, you can use an alternate syntax:
<if > logical equation <then > equations and functions </then > <else > equations and functions </else > </if >
or ...
<if value="logical equation" > <then > equations and functions </then > <else > equations and functions </else > </if >
The logical equation and the equations and functions are the generally the same as above. The differences are:

- If the logical equation evaluates to true, the equations and functions in the `<then > ...</then>` are evaluated
- If the logical equation evaluates to false the equations and functions in the `<else > ...</else>` are evaluated
- The logical-equation between the `<if>` and `</if>` should be before the `<then>`.
- If a `value="logical equation"` attribute is used (inside of the `<if ... >`), and a logical equation is also specified before the `<then >`:the `value="logical equation"` attribute is ignored.
  That is: the logical-equation before the <then> is used instead.

Example ...
<if > myCost gt 100 <then > costLarge=1 taxRate=0.1 </then > <else > costLarge=0 taxRate=0.05 </else > </if > <if value="myPrice gt 25.00" > <then > priceHigh=1 </then > <else > priceHigh=0 </else > </if >
Appendix 6: Using equations and functions (order of processing)
SPEC files and the dSurvey XHTML extensions provide a number of means for evaluating equations that may contain custom javascript functions. This can be a useful way to dynamically modify the display -- say, to add participant and round specific values to appropriate elements.

There are several instances when equations may be evaluated:

1. equations specified in a <init>
2. equations specified in a <params>
3. equations specified in a <calls>
4. equations specified in a <set> special tagname.
5. equations specified in an <do> (if & and when the `<do>` is clicked).
6. equations specified in an <events> (if & and when the event occurs).

The overall order of equation (or function) evaluation is: | equations in `init` and `params` are called before a group is loaded -- hence they can not reference & change the the value of specific XHMTL elements ... Equations specified in a `<call>` within <init> Depending on whether a `retain="1"` is specified ... `retain="1"` not specified: Equations are processed only when the session starts. That is, before the first section (and the first group) is loaded, and never again. `retain="1"` specified: as above, but any variables set in this `call` will not be reset by a `<params>` Hence, <init> is a useful place to specify session-specific parameters, such as low level configuration parameters. equations specified in `<params>` These are called only when the section is first invoked. They are not called when a new group in the current section is displayed. Note that params is where variables provided by the server are read (i.e.; prior results, and instrument configuration parameters). Also note that retained `init` parameters (as noted above) are available to equations contain in a `params`. the following equations are called after a group is loaded -- hence they can reference & change the value of specific XHMTL elements ... equations specified in `<calls>` equations specified in a <set> special tagname, The next equations are called if a button/link is clicked equations specified in a `do` The next equations are called if a specified event occurs. equations specified in an `event` Note that equations specified in a <call> in a exec event are processed here (before any other event is enabled) Notes: equations specified in an `<events>` are called if & when the event occurs. Hence if they occur, they will be typically well after the `<attributes>` and `default, <section>` and `<group>` functions are called. To save the value returned by an equation, start with `varname=` (where `varname` is the name of a session variable).

#### Specifying many equations

To specify many equations to evaluate, one after another, just use multiple lines

Example:
<call> mycost=100 zz=100+mycost myFunction(zz) </call>

#### Default value

If you specify a variable that has not been defined, a value of 0 will be used. Note that this may cause problems when using svy_trueFalse.

Using `<stop />`

- If you want to stop processing before evaluating a list of equations, use `<stop />`. This is typically done within an `<if>`.
  For example ....
  mycost=1.4 * wholeSale <if value="myCost gt 200"> tooMuch=1 `<stop />` </if> nBuy=10 - (myCost*0.05)

#### Conditional evaluation of equations

In `params`, `set`, and within a `call`, you can use if logic to conditionally evaluate equations. As noted above, by using `if` logic you can use variables (such as session variables, including information supplied by the server) to select which equations to evaluate, and which equations to skip. Basically, the use of `if` is the key to customizing your XHTML content.

Note that `if` can be nested -- you can have an `if` inside of an `if`.

Example...
<if value="income gt 100 " > richMan=1 < if value="gotBaby eq 1" > richDad=1 </if> < if value="gotTuitions eq 1" > mildDebt=1 </if> </if>

#### Using `<do>` to repeat

In some cases, you may want to set the value of several sets of variables -- say, to set values used in each of several tickets.

`<do>` can be used to repeat a set of equations. `<do>` can be used in `params`, `set`, and within a `call` (basically, in the same places that `if` can be used).

Syntax ...
<do value="i = iStart,iEnd,iStep" > equations and functions and ifs and dos </do>
This sets up a standard do-loop, with:

- a parameter (`i`)
- that starts at `iStart`,
- that is incremented by `iStep` (`iStep is optional` -- if not specified, `1` is used)
- and that stops when `i` is greater than `iEnd`.

Notes on `i` (or whatever you name it):
- `i` is a session variable, and can be used just like any other session variable.
- within the `<do>` you can set the value of `i`. Be careful: you could end up in an infinite loop! That said, this does give a hacky way of exiting a loop.
- When the loop is done, `i` will be equal to the last value used (if `iStep` is 1, `i` will be equal to `iEnd`).
Note that `iStart, iEnd,` and `iStep` can be variables (their value will be evaluated just before the `<do>` is executed).
Example ...
<do value="i = 1,numTickets" > fee_used[i]=svy_whichOne(useFee,0,fee[i]) </do>
Notes:

- You can nest `<do>` inside of `<if>`, and
- `<if>` inside of `<do>`

Using <break /> to break-out of a `do`

Specifying `<break />` means leave the loop, but continue processing equations after this `<do>`

For example ....
budget=1000 calories=0 <do value="m=1,5"> budget=budget - meal[m] <if value="budget lt 0"> <break /> </if> calories=calories + meal_size[m] </do> alert(' You ate meals with ' $+ calories $+ ' calories ')
Using <continue /> to iterate to go to the next step of a `do`

Specifying `<continue />` means go to the top of the loop and increment the counter

For example ....
income=0 <do value="n=1,10"> income=income+job[n] <if value="income gt 1000"> <continue /> </if> income=income+overTime[n] </do> alert(' Your total income = ' $+ income)

#### Using the value of an equation

The value of an equation (what evaluation of an equation yields) can be used in several manners:

1. If a `varname=` appears at the start of the equation, the `varname` session variable will be assigned the value.
   Example: afterTax= (newPrice-shipping)*(1+tax)
2. If a `arrname[n]=` appears at the start of the equation, the n'th element of the `arrname` session array will be assigned the value.
   Example: outcome[around]=isYes gt 1
   Note that `n` can be a number, or can be a session variable. If it is a session variable, its value will be looked up and used as the index. Thus in the above example, if `around` is equal to `4`, then `outcome[4]` would be set.
3. If a `arrname=Array(v0,v1,...,vn)` is used, then an array (`arrname`) will be created and filled with `v0` to `vn` -- with `arrName[0]=v0` (the first argument in the `Array(...)`), etc.
   Note that you can specify strings by using single quotes, and you can use any math equation & function).(`'`)
   Example: vvs=Array('dog',3,4,'cat',getWord('hello cruel world',2))
4. If a `varname=` is not specified, what happens with the value depends on context.
   1. For equations evaluated in a `init`, `params`, `section`, `group`, or a `call` in an `attributes`: the value is discarded.
   2. For equations in a `set` : the value is displayed.

      If the value is `undefined` is returned (say, because all the equation does is call the `alert` javascript function), or if it is a zero character string (say a `''`), the value is discarded -- the element's `value` attribute will not be modified.

      If several equations are specified, and more than one of them does not start with a `varname=`, then all the values are concatenated (with a space seperating each value). This concatenated value is then used as the elements `value` attribute.

#### Setting other element values, and other attribute values

In some cases, the `varname` in `varname=` can be an element name, or an attribute name .

- For equations except those in the `init` or in a `param` : you can change the `value` attibute of a HTML element of the current group.
  To do this, varname should have the form: `@elemName`, where `elemName` is the name of an HTML element (as specified using `name=` attribute).
  Note that if no such element exists, nothing is done (an error is not reported).
- For equations evaluated in a set: you can change the value of some other attribute in the current element.
  To do this, varname should have the form: `#attName`, where `attName` is the name of the attribute.

  Note that there is no easy way of changing a non-`value` attribute of some other element (of an element other than the current element).

Appendix 7: Converting HTML files to XML module files
If you have older HTML files, that to not adhere to the XHTML (or XML) syntax requirements, you can use htmlToXML.htm. htmlToXML.htm contains a set of HTML code and javascript utilities that will read an HTML file you specify, convert it to XML, alternatively add some doctype headers and do some more obscure conversions, and save the results to a new window. You can then open up this window, view its source, and save it to an .XML file for use as an XHTML modules file.

You will probably have to edit this file before using it as an XML modules file -- say, by adding `<module>` elements.

It is also highly recommended that you open the file (with an .XML extension) in your browser, to make sure the syntax is XML-legal -- if it isn't, you should get an error message.

Appendix 8: The survey base web page
If you use dSurvey's Create & modify an instrument tool, a base-web-page will automatically be created.
Every dSurvey survey must have a base-web-page. This is simply the first web page loaded -- it is what starts the survey!

The survey base web page is fairly simple. In particular, it contains:

- Instructions to retrieve javascript libraries and CSS style sheets

  These include generic libraries, and survey specific libraries.

- A few participant specific variables. These includes the name of the survey, and the participant's id (the `myID` variable), saved as javascript variables.

See sampleHomePage.txt for a well documented example of a base web page.

Appendix 9: The SUBMIT event action

The following lists all of the options available to the <submit> event action; a number of which are infrequently used.

<submit saveOnly="1" noConfirm="1" round="roundVar" toCurrent="1" messageId="divId" notFinal="1" ct="n" var="varname" > |
<message long="a message" varLong="varname" short="one_word_status_message" varShort="varname" />
<save > variables-to-save-definitions <desc> <varname> a description </varname> ... </desc> </save >
</submit>

### Details...

- <Submit> attributes...
  saveOnly="1" | Nothing will be submitted to the server. Instead, as specified above, information specified by the client will be stored for later use. How is `saveOnly` used? One can have several `submit` events, each associated with a different page of questions, and each with a `saveOnly="1"` attribute. Finally, you would use a `submit` element without `saveOnly="1"` -- this would actually submit information to the server, including information retained by these prior (`saveonly="1"`) `submits`.
- noConfirm="1" | Optional. If specified, than the `confirm` feature of the <radio> special tagname will be suppressed. This is useful if you want to force a submit (say, due to a `<query>`), regardless of whether a required `<radio>` has been chosen.
- round="roundVar" | Optional. A value, or a variable name, specifying what round this is. If not specified, the value of the `nowRound` variable is used. Note: failure to specify a valid `roundVar` (either explicitily or using the `nowRound` default) may lead to the server not saving the submitted variables (say, if the `reSubmit` session-descriptor variable is set to 0).
- toCurrent="1" Optional. | If specified, than submitted values are stored in the server's `current round` submitted data archive. If not specified, the submitted values are stored inthe server's `all rounds` submitted data archive. This option is used with the `getCurrent="1"` option of the getSubmitted control-panel action.
- notFinal="1" | If specified, when the data is submitted to the server, the data submitted to the server will set the notFinal variable to 1. Otherwise (say, if `notFinal="1"` is not specified), this `notFinal` submitted variable will equal 0.
- ct="n" | If specified, when the data is submitted to the server, the data submitted to the server will set the ct variable to `n`. Otherwise (say, if `ct="n"` is not specified), this `ct` submitted variable will equal 1.
- messageId="divd" | Optional. divId should be the `id` attribute of an XHTML element (such as a `div`) to use when displaying `message`. If not specified, the alert message area is used.
- var="varname" | Optional. After the submit, a `varname` session variable will be created that contains a success flag. If `var="varname"` is not specified, `_submitStatus` is used as the `varname`. If the submit is successful, `varname` will equal `1`. If an error occurs, `varname` will equal `ERROR: error message`, where the error message briefly describes the error. This varname can be used like any other global variable. For example, after the `submit` you can use `varname` in an `if` to control whether or not to advance to the next group. Warning: you shouldnot use `var="varname"` with `saveOnly` -- no `varname` variable will be created (because nothing is submitted to the server).
- <message> attributes...
  long="a message" | When values are submitted to the server, the `a message` is displayed on the particpant's browser). This message disappears after the response has been successfully recieved by the server. Note that if the server fails to acknowledge reciept of the submitted information, an error occurs.
- varLong="varname" | Optional. This is only used if a `long` attribute is not specified. It's effect is the same as `long`, except instead of a string, use the value of the `varname` variable as the long-message. `varname` may point to a session variable, or to an XHTML element (if it starts with a `@`).
- short="one_word_status_message" | Optional. A one word status message that the server can use to track each client's current status.
- varShort="varname" | Optional. This is only used if a `short` attribute is not specified. It's effect is the same as `short`, except instead of a string, use the value of the `varname` variable as the short-message. `varname` may point to a session variable, or to an XHTML element (if it starts with a `@`).
- <save> `variables-to-save-definitions` </save>
  variables to save definitions | Optional. You can specify extra variables to submit to the server using `save`. If specified, variables-to-save-definitions should be a mutli-line string. Each line will contain a simple equality of the form: `submitVar=a_variable`, where...
`submitVar` : a variable name to submit to the server `a_variable`: value to submit to the server (using `submitVar` as the name). `a_variable` can be a number, a ' quoted string', a session variable or session array element, or the value of an XHTML element (prefaced with a @). It can not refer to an attribute's value (that is, it can not be `#attname`). And it can not be an equation.

- Shortcuts | `aVar` (no = sign) : same as `aVar=aVar` preceding an equation with a `var` means save this to a dSurvey session variable (do not save it to the server). Example: roundCost3=roundCosts[3] var thisRoundCost3=roundCosts[3] The value of `roundCosts[3]` is saved to the server using a name of roundCost3. Also, a new dSurvey session variable, `thisRoundCost3` will be created and given the current value of `roundCosts[3]` If you use this syntax, you must follow it with an equation. Thus, `var myPrice` is incorrect. Use of * and arrays. Assuming some array (`arrName`) exists, `*` can be used to expand the list of variables to save In the following examples, assume that `arrName[1], arrName[2]`, and `arrName[3]` exist. `arrName[*]` would yield: arrName[1]=arrName[1] arrName[2]=arrName[2] arrName[3]=arrName[3] `newName[*]=arrName[*]` would yield: newName[1]=arrName[1] newName[2]=arrName[2] newName[3]=arrName[3] `oddName*=arrName[*]` would yield: oddName1=arrName[1] oddName2=arrName[2] oddName3=arrName[3] Note the * on the rhs must refer to array elements (otherwise no expansion is attempted)

- Example... | <save > thisType='practice' myCost=cost1 myIncome=income[1] offers[*] earn[*]=myEarn[*] </save>

- Descriptions Optional. You can include descriptions of the `save` variables between a `<desc>` and a `</desc>`. These descriptions are used by the Create a data dictionary utility. | <desc > <varname1> a description <</varname1> ... <varnameN> another description <</varname1> </desc > Note that the `varnameN` should match variable names specifed in the `save`.

  Appendix 10: Creating a simple History

  #### Synopsis: specifying, building, and displaying a simpleHistory

  The use of dSurvey's `simpleHistory` provides a convenient way to for a participant to view his History of decisions and results, simply by clicking on a button.

  > It should be noted that this `<simpleHistory>` capability is convenient, but not particularly powerful. If you are ambitious, it is not too difficult to create a custom History.

  #### There are several steps associated with `simpleHistory`.

  Specifying a `simpleHistory`. | This is done using the `<history>` option of <init>. Note: The bulk of this appendix describes the use of `<history>`.
  Building a `simpleHistory` table. | Rows are added to the `simpleHistory` table whenever a <params> option of `<section>` is processed. Note that you can use attributes within `<params>` to

- `noHistory="1"`: suppress addition of a row to the `simpleHistory` table
- `saveSimple="1"`: backup a row to the server, that can be retrieved later using <recoverSimple> .
  Displaying a `simpleHistory` table. The <history> special tagname is used to create a button that, when clicked by a participant, will display the `simpleHistory` table in a new window.
  Recovering a history table. If the participant must reboot, you can <recoverSimple> history information from prior rounds that will be used to rebuild the `simpleHistory` table.

  Notes: |

- This requires backing up `simpleHistory` rows to the server at they are created.

- If `<vars>` are not specified in the `<history>` option (described below), when values are recovered and the simpleHistory table is rebuilt, there will be no top row of variables names.

  However, after a new round has been submitted, a top row of variables names will be displayed
  If this minor glitch is embarrasing, you should specify `<vars>`!

- Technical note:`dSurvey has to wait and see what variables are submitted before it can construct a list of submtited variables.`

  #### Specifying a `simpleHistory`:the `<history>` option of <init>.
  <history name="aname" where="divid" > <vars> comma (and space) delimited list of variables </vars > <colDesc> comma delimited list of column headers </colDesc> <colStyle> comma delimited list of styles to use in each row of the table (except the top row) <colStyle> <recode> <varname> old = new ... </varname> ... </recode> <header> Optional. Content to place above the historyTable. HTML can be used, including the special tagnames. </header>/ <footer> Optional. Content to place above the historyTable. HTML can be used, including the special tagnames. </footer>/ </history>
  where:

  `name="aname"` | Optional. You can create seperate and independent Histories by specyfing several different `<history>` with different `aname`s. Just be sure to properly specify `name="aname"` in the <history> special tagname.
  `where="divid"` | Optional. The `where="divid"` is optional. If not specified, a popup window (with a name of `simpleHistoryWIndow` is used to display the historyTable. If specified, `divid` should be the `id` of an existing element (typically a `<div>`) -- the historyTable will be written to this element (overwriting any existing content).
  `<vars>` | These are the variables to display in the historyTable. If not specified, the variables submitted to the server will be used. Each variable in should be seperated by a comma or a spaces. A comma signifies a new column, and a space signifies a new line (within a table cell). Example: <vars> cost1 offer1 , cost2 offer2 , , totalEarnings </vars> `cost1` and `offer1` will be displayed in the same column (on seperate lines). `cost2` and `offer2` will be displayed in the same column (on seperate lines). an empty cell will be inserted `totalEarnings` will be displayed Notes:

- seperate values will be stored for each round of the session, since each row of the historyTable contains values for a unique round.
- Do not refer to `prior` variables (that is, do not use dotted variable names).
  `<colDesc>` Optional. The column headers-- what is displayed on the top row of the historyTable.
  If not specified, the variable name is displayed.
  Use commas to seperate column headers (that means you can not use commas in your header).
  Note that you can use HTML in the column descriptors (such as `<br />`), but not the special tagnames.

  Example...
  <colDesc> First ticket <br/> results , Second ticket , == , Totals </colDesc>
  `<colStyle>` Optional. Comma delimited list of styles to use in each column the table (except columns in the top row). There should be as many items (seperated by commas) as items in the `<vars>`. That is, each style corresponds to a cell in a row, and each cell may display zero, one, or several variables.

  Example...
  <colStyle> color:red;background-color:lime; , color:blue;font-weight:800, , font-style:oblique;text-decoration:underline </colStyle>
  `<recode>` Optional. Used to recode values displayed in the historyTable.

  To recode a variable, say with a name of `avar`, specify within the `<recode>`:
  <avar> oldValue = new value string oldValues = new value string oldvalues = new value with * also </avar>
  Each value to recode should be on its own line. Or, you can specify several oldValues at once (in a space delimited list). The `new value string` can be any string, but it should not include HTML (such as `<br/>`).

  Notes:
- If you specify: `= new value string`, then an empty string will be recoded to the `new value string`.
- If you specify: `oldValue =` , then a blank is displayed (when `avar` equals `oldValue`.
- Trick: you can use the `* = new value string` to recode anything that doesn't match some other line.
- Trick: you can include a `*` in the `new value string` -- it will be replaced by the `oldValue`. This can be useful if you use a space delimited list of `oldValues`, or if you use `*` as the `oldValue`.
  To suppress this replacement, include a `replace=""` attribute in the `<recode>`. Or, to use a different character (not a `*`), use `replace="aChar"`.
  For example, to use a `%` character, use `replace="%"`. Example ...
  <recode > <isDemo> 0 = real round 1 = demo round </isDemo> <earlyRound> 0 1 2 = practice round * = non-practice round </earlyRound> <costType> 0 = <tt>low</tt> cost 1 = medium cost 2 = <b>high</b> cost * = unknown cost </costType> <myPrice> 0 = <tt>free</tt> cost * = Price paid= * </myPrice> </recode >
  Appendix 11: Working with recoverPrior to create a history

  #### Specifying, building, and displaying a customized History

  The use of dSurvey's `recoverPrior`, along with `uploadData` provides a relatively straightforward means of re-creating a custom history page of decisions and results. This can be useful if the client refreshes his brower (thereby losing all information stored about the current session).

  > It should be noted that creating (and re-creating) a custom history page gives the survey designer a lot of power, but does require a fair amount of specificiation. If you are willing to accept a simpler design, consider creating a simple History!

  `<recoverPrior toModule="aModule" modules="modList" '>` will do the following:
  - Download, from the server, the `history` archive.
    The history archive should (if properly created) contain information on all participants for all rounds of the session.
  - Using this downloaded data, populate a `prior variables` internal database. This is a database that is automatically updated by <params>. Note that only variables specified in the history archive will be created (so be sure so specify, in `uploadData`, all the variables you will want to use when creating a history). contains information on all participants
  - If `modules` and `toModule` are specified..
  - Erase the contents (if any) of `toModule`, and then
    1. Set the `recent` round variables equal to the values specified for round 1.
    2. Process the modules in `modlist`. These modules can contain all the special tagnames. In particular, these modules can refer to `recent` variables, using a `varname.` syntax.
       For example: `<show var="myBid." />`
    3. Take the results of this processing and append it to the `toModule` module.
  - Repeat the above for rounds 2, etc. (up until the last round saved in the history archive).
  At the end of this process, the `amodule` can be used in a `<popup >`, etc.

  #### Notes

  - More details on creating a custom History.

  - Ambitious programmers can work directly with the `priorRound` database -- see the description of `read_priorGlobal`, `save_priorGlobal`, `Save_GlobalHistory`, `Retrieve_GlobalHistory`, `Reset_recentHistory` in svyInputs2.txt.

  - The history archive contains data for all participants. `recoverPrior` will extract results just for this participant. That means that information on other paritcipants (that appears in the history archive) will be discarded.
    And yes, this is a potential security flaw -- yet another reason why dSurvey is not a highly secure platform.

  - `download="0"` , if specified, will suppress downloading the history archive, hence the prior variables will not be modified.
    Thus, it is not used very often. One possible use is if you want to create all at once, even if a browser refresh has not occurred, a history page (rather than incrementally build it whenever a new round starts).

  - You can display processing status on screen by specifying a `div` (or `span`) with an `id="_recoverPriorStatus"`. Status messages (of the download and build a history task) will be displayed inside of this element. Note that this should specifed in the `<group>` that contains the `<recoverPrior>`.
  Appendix 12: The dSurvey message feature

  #### Using the dSurvey message feature

  The dSurvey message feature allows participants in a survey, and the survey administrator, to send messages to each other. A number of features are supported, including limiting who each participant can send messages to.

  Enabling, and changing, these dSurvey messages features is accomplished in several steps. The general rule is that participants need to be informed of what features are enabled. This is done in two ways: first through the `SPEC` file, and after that through `CAP` files (note that specifying message features in the SPEC file is slightly deprecated).
  1. `Using the SPEC file`. In the section of SPEC files you can specify a <message> section. In `<init>... <message>` you can specify a variety of message features. This includes specifying where, on the participant's browser screen, to display a read messages button. Note that the message features specified here can also be specified in CAP files, while the location of the button can only be specified in this `<init><message>` section. Reminder: Participants process the `<init>` section of the SPEC file right after joining a session.
  2. `Using CAP files`. Whenever a partcipant read a CAP file (say, when a <params> in a <section> is proccessed), his message features can be updated. Specifically, a `<message>` section of the CAP file is used, which can be set in several manners:
     1. In the <message_options> section of the session descriptor file, the default values of the dsurvey messages options are typically specified. When a control panel starts, it will use this `<message_options>` to initialize a `message_options` control variable. The value of the `message_options` control variable will be included in CAP file whenever a <message> section is specified in a <postCap>.
        Note: values specified in CAP files override values set in the <init> section of the SPEC file.
     2. The button, at the top of the control panel, contains a button that can be used to change this `message_options` control variable whenever desired. Then, when a CAP file is written, the current value of `message_options` will be written to the `<message>` section of the CAP file.
     3. advanced administrators: you can set the `messages_options.c` control variable (i.e.; in a `<do>`).

  #### <message> in <init>

  `<message>` (inside of <init>) is a (slightly deprecated) means of enabling the dSurvey message feature.

  Reminder: instead of using <message> in <init>, we recommend using the <message_options> section of the session descriptor file.
  Syntax:
  <message where="anid" > <options> optionList </options> </message >

  `where="anid"` | If specified, `anid` should be the `id` of an element. Clicking on this element will display the send/recieve messages input elements. If not specified, a button will be placed in a fixed position at the top of the screen (the button stays there even when the screen is scrolled).
  `<options> optionList </options>` | `<options>` is used to initialize how/when to display messages. Actually, use of `<options>` is somewhat deprecated: in general it is more convenient and flexible to specify message options in the <message> section of a CAP file (and to initialize this value using the `message_options` variable in the session descriptor file). However, the syntax of these means of specifying message options is identical. A comma delimited string of instructions is expected, which may include any mixture of the following (note that late appearing instructions can override earlier ones) :

- `notify`: When a new message is retrieved, a screen message will be displayed informing the participant that a new message has arrived. This is ignored if polling is disabled.
- `nonotify`: Disable notifiation (the default)

- `show`: Display the `message` button, or its custom replacement (the default))
- `noshow`: Do not display the `message` button (or its custom replacement)

- `enable`: Enable message sending and recieving (the default) -- this does not imply a `show`
- `disable`: Disable message sending and recieving -- implies `noshow`
- `notesOnly`: Disable message sending and recieving, but permit writing notes /tt>

- `sendAll`: Allow messages to be sent to anyone (the default)
- `noSend`: Do not allow messages to be sent, but do allow reciept of messages
- `adminSend`: Do not allow messages to be sent to participants, but do allow messages to the administrator (`adminSend` trumps `noSend`).
- `sendIf= equation` : Allow messages to be sent to participants when the equation is satisfied.
  `equation` should be a standard logical equation used in SPEC files. There is one addition: you can specify `message` variables by using the `messageVar('varName')` in the equation.

  ### Details on `messageVar()`

  `messageVar()` can be used to compare `message variables` (variables specified in the `<message>` section of CAP file) against other (i.e.; participant specific) variables. When used in `SENDIF=anEquation`, this allows you to limit who each participant can send a message to.
  Thus: you can control who can communicate with who!
  Details...
  - Syntax: `messageVar('varname')` -- for each session-participant, the value of the `varname message variable` is extracted.
  - `varname` must be enclosed in single-quotes.
  - For elements of an array, you should use a `varname_i_` syntax inside of `messageVar()` (rather then using the normal `varname[i]` syntax).
  - Examples:
  - `SENDIF= myType eq messageVar('mytype')` (only allow messages to be sent to participants that are the same type as you).
  - `SENDIF= group[1] eq messageVar('group_1_')` (only allow messages to be sent to participants with a group[1] value that is the same as yours).
  - Technical note: `messageVar()` can be used in dSurvey functions (such as used in a `<call>`. However, the syntax when used as a stand-alone function is: `avalue=messageVar('varname',ith)`, where `ith` is the ith participant specified in the `messageData` database. Note that `ith` is an order of read, and is not related to a participants `ID` (or any other participant info).
    Hint: to find the number of participants stored in the `messageData` database, you can use `ict=messageVar()`.

- `poll time=nseconds` : Controls how often messages are downloaded from the server.
  By default, messages will be retrieved only when the participant specifically requests. If `poll=nseconds` is specified, then every `nseconds` messages will be downloaded from the server.

  If `poll=0`, then this automatic downloading is disabled (the participant will have to specifically request a message retrieval).

- `nopoll` : same as `POLL=0` (the default)

  #### Retrieving addressess

  The dSurvey message feature requires `current participant` data, which includes the addresses for participants enrolled in the session. This is read from the `<message>` section of a CAP file.
  Notes:
- If are using the standard dSurvey instrument creation tools, a `<message>` section will always be included in CAP files.
- If new participants join a session, their addresses will become available to other participants when the CAP files are refreshed, and the participants downloads this updated CAP file.
- In addition to client addresses, the client's `NAME`, `NICKNAME`, and `CONTACT` are available. Ambitious instrument designers can include other `message` data (see Customizing messages and <message> for more details).

  #### Using the dsurveyMessages function

  `<message>` is used to intialize the dSurvey message features. After initialization, you can manage how `messages` work by using the `dsurveyMessages` function -- for example, in a <call> when a section starts.
  Note: instead of explicitily calling `dsurveyMessages()`, it may be more convenient to update `message_options` via the control panel (by updating CAP files with a modified <message> section).
  Syntax:: `dsurveyMessages(optionList)`, where `optionList` is described above.

  Examples:
  dsurveyMessages('show') dsurveyMessages('noshow') dsurveyMessages('show notify poll=30')

  #### Customizing messages

  more later
  Appendix 13: Somewhat deprecated features
  The following lists dSurvey features that are now somewhat deprecated. We mention them because there might be times when they are convenient to use.

  #### Within `section`, a way of calling equations (for whenever the section is displayed).

  This has been replaced by using entries in <calls>

  `<call after="1">` | Specifies section-specific equations to evaluate. There can be zero, or one, or more `<call>` per `<section>` These section-specific equations are evaluated each time a group from this section is loaded. In contast, equations in <params> are called only when the section is first loaded. You can review the order that equations are processed. The equations, which can call custom javascript functions provided by you, can be used to customize the content in fancy ways. Depending on if `after="1"` is specified, these equations are evaluated either before or after the group specific equations. Note that by default, the default functions are called before the section and group specific equations (and the functions they may contain). Note that it does not matter where, within a `section` a `<call>` is specified. For readability purposes, placing `<call>` at the top of the section is recommended, but is not required.
  after="1" | Optional. If specified, evaluate these section-specific equations after any group-specific equations. If not specified, evaluate these section-specific equations before any group-specific equations.
  equation | The `equation` can be any valid javascript equation, possibly beginning with `varname=` (so that the value returned by the function will be saved in the `varname` session variable). See appendix 6 for the details.

  Within a `group`, a way of calling equations (for whenever the section is displayed). This has been replaced by using entries in <calls>

  <call> | In addition to section-specific equations, you can evaluate group specific equations. The syntax is the same as the section-specific equations. However, the `after="1"` attribute can not be used! You can review the order that equations are processed.

  These section and group `<call>` are invoked in the following order (after equations specified in `<set>` in `<attributes>`.

  1. section-specific equations (using `<call>`) that do NOT have an `after="1"` attribute (in their `<call>`)
     These are called whenever a group, from this section, is displayed.
  2. group-specific equations (using `<call>`)
     These are called only for the group that they appear in.
  3. section-specfic equations (using `<call>`) that have an `after="1"` attribute (in their `<call>`)
     These are called whenever a group, from this section, is displayed.
  In a call, used in a section or a group, `if` is used to control which equations & functions to evaluate:

  <section > ... <call > ... <if value="logical equation" > equations and functions </if> ... </call > ... <group > ... <call > ... <if value="logical equation" > equations and functions </if> ... </call > ... </group> </section>

  #### Using setValue

  If an element (such as a `span` has class of `set`, then equations specified in a `setValue` will be evaluted. the details...

  #### The <set> attribute

  Using `<set>` inside of a `<attributes>` is deprecated. Use a `<set>` with `<use>`
  Within `<attributes>`, `<set>` can be used to set the `value` attribute of an XHTML element. Compared to other items within a `<attributes>`, `set` is different.
  - For other items, the content is used as is.
  - For `set`, the content is treated as equations and functions.
  Note that other methods of setting values include the setValue attribute, and the <set> special tagname.
  Syntax:
  <attributes> <anId> <set> an_equation avar=an_equation <if value="logical equation"> an_equation avar=an_equation </if> </set> </anId> </attributes>
  where...
  - Within a `<set>`: you can specify zero, or one `<if>` blocks.

    Careful: if you use `<if>` outside of a `<set>`: it will be interpreted as a specification of an `if` attribute.

  - The `logical equation` attribute of `if` can be quite long (and may contain new-lines).
  - You can specify zero, one, or many `equations`
  - Before a `<if>`
  - After a `<if>`
  - Inside a `<if>`
  - You should not use `#attribute_values` in the `logical equation` statements. A work around is to set a temporary variable (equal to an `#attribute`) before the `if`, and then use this temporary variable in the `logical equation`.

  #### How is `<set>`, in `<attributes>`, used?

  Assuming that there exists, in the current group, an XHTML element with an `id` that matches the `<anId>`, and a `<set>` has been properly specified ...
  1. Each equation inside of the `<set>` is processed in order of appearance. That means that earlier equations can effect the processing of later elements.
  2. If you specify a `varname=` before an equation, the `varname` variable will be assigned the value of the equation
     `varname` can be a
  3. Session variable name. `tval1=cost - prepay`
  4. The value of an XHTML element. `@Earning=wage - tval1`
  5. The value of an attribute (of this element). `#value=wage/2` `varname` can contain a #, which will be replaced by the elements `IDX` value (if one exists). For example:
  6. `tval1=cost[#] - prepay`
  7. `@Earning=wage[#] - tval1`
  8. `@otherValue#=wage/2`
  9. If you do not specify a `varname=`, the equation's value will be used to set the element's `value` attribute.
     Note: if you do not specify a `varname=`, and the equation includes a function, the function will be called but no value will be saved.
  10. If there are multiple equations that do not have a `varname=`, their values will be concatenated.

  Example: | <attributes > <myElem1> <set > factor1=33.15 foo=chkMyValues(myPrice,100) newCost=figCost(myPrice,factor1,2) 'Your cost is= ' $+ newCost </set > </myElem1> </attributes >

  Notes:
  - if you want to use a string, be sure to 'quote it'. For example:
    `'hello world'`
  - You can use <if> and <do>,
  - If you want to stop processing all equations (those in and after the `do`), use <stop />.
    Or, to break out of a `do`, use <break />.
    Or, to jump to the top of a `do`, use <continue />.
    Note that `<stop />` and `<break />` are typically used inside of an `<if />`.

  #### Working with <create>

  #### Building a dynamic table

  We recommend using the <if> and <repeat> special-tagnames to build a dynamic table
  Suppose you want to build a dynamic table, one whose contents depends on survey or participant specific parameters. Modular surveys lets you do this, by allowing you to specify what rows to include as a function of these parameters.

  In particular, `<create>` can be used.

  1. Construct (in a module file) several modules that consist of standalone rows (`<tr>`). That is, modules that do not have a `<table>` element (enclosing the `<tr>`).
     Let's call them `myrow1, myrow2a, myrow2b, myrow4` .
  2. Specify `table` as the `tagname`.
     Eg: `<create tagname="table" modulename="myTable" >`
  3. Inside the `<create>`, specify one, or several `<content>`, each of which includes a `<modules>` that references one of these modules. To be dynamic, `<if>` may also be used in these `<content>`.
  4. A new module (i.e.; `myTable`) will be created. Its base-element will have `table` tagname, and its rows will be as determined by step iii.
  Example:
  <create tagname="table" moduleName="myTable" > <content > < module > myrow1 < /module > </content > <content > <if> thisVersion==1 </if> <module> myrow2a </module> </content> <content > <if> thisVersion==2 </if> <module> myrow2b </module> </content> <content > < module > myrow4 < /module > </content> </create >
  This causes a table to be created stored as a module named `myTable`. Depending on the value of the `thisVersion` session variable, the 2nd row of this table will either be the one specified in `myrow2a`, or the one from `myrow2b`.

  You can use this new `myTable` module just like any other module!

  Caution: When building dynamic tables, be sure that each `content` is a valid row -- i.e.; that the `modules` you use start with a `tr`.

  #### Repeating modules

  Repeating modules is mostly deprecated. Use the REPEAT special-tagname instead.
  There may be cases where you need to replicate some content a dynamic number of times. For example, suppose your survey has asks people to fill out a ticket -- say, to enter a bid offer. You may want to ask participants to fill out 1,2 or 3 different tickets at a time. And you may want to change the number of tickets across rounds.

  The `repeat` attribute of `<content>` can be used to do this. In fact, you can use `repeat` to create a table with several replications of the same row (say, specified as stand-alone rows, as discussed above).

  The `repeat` specifies how many times to replicate everything specified in a `<content>` -- `<literal>`, `<modules>`, etc.
  This replication is exact: with one important exception -- an `idx` attribute can be added to the elements being repeated. This `idx` attribute is used by several of the dSurvey XHTML extensions, such as extentions used to assign dynamic values (say, using participant and ticket specific parameters).

  The value of the `idx` attribute is the replication number.. Thus, if `repeat=3`, in the first replication `idx="1"` is used, in the 2nd `idx="2"`, and `idx="3"` in the third replication.

  - By default, `span`, `div`, and `input` elements will have `idx` attributes added.
  - You can use `idxTags` to change this default. `idxTags` should contains a space delimited list of tagnames.
    For example: `idxtags="span div option select"`.
  - or... you can also use `idxClass` to specify a `class` to look for -- any element with this class will have the `idx` attribute added.
    For example: `idxClass="ticket"`.
  - As discussed above, you can use `tagname` to specify the tag of the base-element. If you do not include a `tagname` attribute in `<create>`, `div` is used.
  - You can set the number of replications to be the current value of session variable. For example: `repeat=numDo`.
  Example:
  <create moduleName="myTickets" > <content > < module > q_Intro < /module > </content > <content repeat="3" idxTags="input div" > < module > questions < /module > </content > </create >
  Example (note use of `idxTags="0"` -- only elements with a `ticket` class will have an `idx` attribute added):
  <create moduleName="myTickets" tagname="table" > <content > < module > ticketHeader < /module > </content > <content repeat="numTickets" idxClass="ticket" idxTags="0" > < module > ticketValues < /module > </content > <content > < module > ticketSummary < /module > </content > </create >

  Last updated 30 May 2010