SavingResults

## Working with dSurvey's control panel programs

`dSurvey` uses a `control panel` to administer `dSurvey` sessions. In particular, each session is associated with a control panel program. A dSurvey control panel program is an XML file that dSurvey treats as a script, a script that contains instructions on how to manipulate data & files associated with the session.

This document describes how to write, and use, a control panel program.

| Control panel programs are used to control a session. However, control panel programs are instrument-specific. Thus, all sessions created from a given instrument will use the same control-panel program file. Note that an instrument's (hence all its sessions) control panel program is stored in the `/dsurvey/instruments/anInstrument` directory (where `anInstrument` is the name of the instrument). And, by default, it will have a name of `control.xml`.

Note: to actually invoke a control panel, use the open a control panel option on the main dSurvey administrative page.
You can use the Modify an instrument's control, parameter, SPEC, and module files utility to create and edit control panel files.

### Contents

- Control panel program basics
- A note on variables
- A note on functions
- INCLUDE
- INIT
- ATTRIBUTES
- the usestyle attribute
- the help attribute
- the change attribute
- The If modifier
- Examples:
- DO
- a task-list
- useful functions
- FORM
- special tagnames for inputting data
- PANEL

Control panel program basics
Five major types of actions are recognized. With each "action", a number of options & sub-actions can be specified.
Since this is an XML file, actions (and sub-actions) are specified by using <tagNames> ... </tagName), with subactions nested between the start and end tagNames.
The five major actions are: INIT, ATTRIBUTES, DO, FORM, and DISPLAY.

INIT | intialize control variables
ATTRIBUTES | Specify attributes to be added to elements in the control panel scripts.
DO | perform a variety of tasks specified in a task-list, such as getting and posting server variables and parameter files
FORM | define a form containing input fields for setting variables and selectively performing tasks.
PANEL | specify (using HTML) the contents of the control-panel, the stuff displayed in the main browser window

In addition you can use INCLUDE to include subroutines anywhere in your control panel program.

Note on case sensitivity: | in control panel scripts, tagnames are almost always case inSensitive. However, as XML files, you must use the same "start" and "end" tagname. That is, you can use whatever case you like, just be sure it is the same. For example: `<Init > .... </Init>` is okay. `<INIT > .... </Init>` is an error.

A note on variables
dSurvey control panels work with several different kinds of variables. dSurvey control panel can read, change, and save these variables

The principal kinds of variables are "general", "server", and "control"

`General` | variables set in a session-specific parameters file.
`Server` | dynamic/temporary variables set by the server.
`Control` | local variables set within this control panel. They are only used in the control panel: participants have no direct access to control variables.

These are specified using the following syntax:

`General` | prepend a '%', or by append a '.G' or a '.GENERAL' Example:`display_max.general, %nTickets`
`Server` | prepend a '@', or by append a '.S' or a '.SERVER' Example:`introStep.server, @startRound`
`Control` | prepend a '#', or by append a '.C' or a '.CONTROL' Example:`totPaid.control, #didAccept`

Note that if nothing is prepended or appended, a default variable type will be assumed. This default depends on the action.

Several other kinds of variables are also used, though in more limited settings

- `Results` variables are computed using information submitted by participants, and other information
  In <set>, you can reference these variables by using varname.R or varname.RESULTS
- `User` variables are client specific values for variables: so a "user variable" is really a vector (1 element per client). In <set>, you can reference these variables by using varname.U
- `currentParticipant` variables are permanent variables associated with each participant (such as the participant's name, nickname, and contact information)

A note on functions
In addition to using variables, control panels can work with functions, including:
- dSurvey i/o functions
- Math and statistical functions
  and your own
- custom functions (say to compute results).
<include>
<include> and <sub> are used to include external files, and to define `subroutines` that can be included anywhere in your control panel program.

- When `< include file="urlToXMLFile" />` is used, it will get, from the server, the contents of `urlToXMLfile`, and include it in the control panel at the location of this `<include>`.
  Notes:
- `urltoXMLFile` can be a fully qualified URL, and should point to a valid XML file.
- or, if not qualified (if not starting with a `/`), it will be relative to the home directory of this instrument.
- Examples: `<include file="/dsurvey/lib/control_generic.xml" />`
  `<include file="myControls.xml" />` (if the instrument is `inst3`, this resolves to `/dsurvey/instruments/inst3/myControls.xml`).

- If `urlToXMLfile` does not exist, an error message will be written to the screen and to the status area.
  However, if `okMiss="1"` is included in the `<include >`, then no error message is written (a warning is written to the status area).
- If `urlToXMLfile` has an XML error, an error message will be written to the screen.
- When `< include sub="subname" />` is used, it will copy the contents of a `sub` (to the location of the `include`).

  Syntax:

  ... <include sub="subName" /> .. various DO, FORM, and other control panel stuff .. <sub name="subName" > .. various DO, FORM, and other control panel stuff .. ... </sub>
  Note that `sub` must be specified in the `include`, and `name` must be specified in the `sub`.

<init>
`<init>` is used to initialize control variables, load custom libraries, and execute a `DO` action.
Only one `<init>` can be specified per control panel program.
Syntax:
<init> <set> a=b ... </set> <load name="libraryName.js" /> <do name="doName" /> <form name="doForm" /> </init>
Notes:
- the order of `set`, `load`, `do`, and `form` is ignored.
- You can use `<include>` inside of an `<init>`.

`<set>`
  `<set>` is always processed first.

  You can specify zero, one, or many `<set>` in an `<init>`.

  In a <set> component of an `init`, you can specify `control` variables (one variable per line). Note that only `control` variables can be specified: you can not specify `general` variables. Therefore, you should not append a `.C` to the variable name. If you want to initalize general parameters, you can use <DO> inside of `<init>`

  Example:
  <init> <set> startOrder=On demand showD1=0 </set> </init>
  Notes:
  - Strings are not quoted.
  - `<set>` used inside of a `<DO>` can also be used to set general, user, and control variables.
  - You can specify `alert('a message')`, but (unlike in other parts of the control panel), the `a message` should not contain variable names (that is, you can not use the $+ syntax to build a message that contains variable values).
`<load>`
  `<load>` is always processed second.

  You can specify zero, one, or more `<LOAD>`.

  The `libraryname.js` should be a valid url to a javascript library containing functions that this session may need.

  Note that relative urls will be relative to the /dsurvey/admins/ directory. Typically, this won't be correct. Rather, something like the following should be used

  <load name="/dsurvey/instruments/yourInstName/lib/alib.js" />
  where "yourInstName" is the instrument-directory for this session (recollect that sessions are always "created" using an instrument).

`<do>`
  `<do>` is always processed third.
  `<DO>` is optional. It is used to specify initializations <DO> that will be executed when the control panel is invoked.

  You can specify zero, one, or more `<DO>`.

  These `<DO>`s will be executed (in order of appearance) after `<SET>` and after `<LOAD>`, and after PANEL has been processed (after the control panel content has been displayed).

  You can specify zero, one, or more `DO`.
  Some nice features of initialization <DO>s are the ability to set General variables (using `<set>`), and dynamically set some displayed content (using `<updateDiv>)`.

  Syntax:
  <do name="doName" />
  where `doName` identifies a <DO> block. If no such block exists, an error message is displayed.

`<form>`
  `<form>` is always processed last.
  `<FORM>` is optional. It is used to specify an initialization <FORM> that will be displayed when the control panel is invoked. This `FORM` will be executed (in order of appearance) after `<DO&;gt;` (which means after the control panel content has been displayed).

  You can specify zero, or one `FORM`.
  For example, `<FORM>` can be used to ask the administrator to set some session-specific parameters.

  Syntax:
  <form name="formName" />
  where `formName` identifies a <FORM> block. If no such block exists, an error message is displayed.

  Notes:
  - Only one `<form>` can be specified. It will be displayed after all of the `<do>` are processed.
  - However, this `<form>` can invoke a `<do>` (i.e.; by using a `SUBMIT`).
  - The form will be displayed with the options table suppressed (i.e.; as if a `vuTasksTable="NO"` were specified).

Notes:

- init is read when the control panel program is first read. Thus, only control variables can be set. Which means that variables names should be as is (do not prepend, or append, anything)
- However, a `<do>` invoked by `<init>` can initialize general parameters.
- If <reset /> is used, these "initialized" control parameters will be removed (along with any other control variables)
  <attributes>
  In the spirit of seperating presentation from content, one can define attributes for any element specified in an XML control panel program. This is done in the <attributes> section. The syntax is simple
  <attributes> <anID > <anAttribute> some text </anAttribute> <anAttribute2> some text </anAttribute2> </anID> <anID2> ... </anID2> .. </attributes>
  1. start and end with <attributes> and </attributes>
  2. you can have 1 or more <anID> ... </anID>, where "anID" should be the "id" of some element in this XML file.
  3. within each <anID>, you can define several attributes, with each attribute defined using an <attributeName> value of attribute </attributeName>
  Thus, to use <attributes>, you must specify approriate IDs in the elements in this file. For example, in DIV and SPAN elements in the <panel> section, or within <forms>.

  Notes:
  - You can have 0, 1, or more than one `<attributes>` in a `control-panel` file.
    It is probably cleaner to have just one `<attributes>`in a `control-panel` file.
    But it can be useful to include other `<attributes>` via an `<include>` file, say as part of a section+.
  - `<attributes>` can be anywhere in the `control-panel` file (though it must be a first level element of the XML file).
  There are several special attributes:
- `usestyle`
- `help`
- `change` and a special modifier ...
- `if`
  the usestyle attribute
  The `usestyle` is a synonym for `style`.
  The only reason to use `usestyle` (instead of `style`) is because Internet Explorer is buggy.
  In particular, Internet Explorer doesn't like to see `<style ...>`.
  So, if you will only use FireFox (or some other standards compliant brower), you can use `<style>`. But, if you might use Internet Explorer, use `<usestyle>`.
  Note: `usestyle` will also be understood by FireFox, etc. So there is no technical reason not to use `usestyle` (perhaps it leads to a less human readable file).
  the help attribute
  Syntax:
  <help> A message that <b>can</b> contain HTML. And that that can be several lines long. <.help>
  The help attribute is used in elements that are meant to be displayed: that is, for elements in the <panel>, or in a <form>.

  The help attribute is often used to specify context sensitive help messages. That is, helpful tips on a particular topic.

  For all elements that a `<help>` applies to:
  1. add a title attribute equal to the first line of the contents of the `<help>`: with all HTML tags removed.
  2. add a onClick event that will display this content (when the element is clicked) -- retaining the HTML tags
  3. underline, and use a blue font, the innerHTML of this element
  The message will be displayed in the `dataMessage` box: a yellow box that appears toward the bottom of the browser screen, and that will go away when clicked on.

  Notes:

- If you specify a `<style>` (or a `<useStyle>`) attribute, the `underline, blue font` style will not be used. That is, if you specify a `<style>`, that style will be used!
- If you specify a `<title>`, then the `first line of the contents` will not be used as the title. That is, if you specify a `<title>`, that title will be used!

- Note: you can specify a `help` attribute directly in the element, but it won't be nearly as powerful. So we don't recommend it.
  Example:
  <attributes > <myReminder > <help>Don't forget to enter your offer! <br /> If you <em>forget</em>, you will earn <b>zero</b>> dollars in this round! </help> </myReminder > </attributes > and in the your <panel> section ... <div id="myReminder"> Are you ready to submit </div>
  In the above example,
- the title -- displayed when you mouseover the Are you ready to submit -- will be
  Don't forget to to enter your offer!
- the message -- displayed in the `dataMessageBox` when you click the Are you ready to submit -- will be:
  Don't forget to enter your offer
  If you forget, you will earn zero dollars in this round!
  using <change>
  `<change>` in `<attributes>` is used for input-field elements: such as `<input>` and `<step>`.
  It is designed to specify actions to take when an input-field element is clicked, changed, or otherwise selected.

  Several sub-actions can be specified under `change`:

  `<confirm>` | `<confirm>` will ask the administrator to confirm his choice, using a javascript confirmation box. If the administrator does not confirm (hits cancel), then the variable specified in this input field will not be changed.
  `<alert>` | display a message in the javascript alert box, the "_controlStatus" area, or the "dataMessage" area
  `<set>` | set the value of a control or general variable(s)
  `<display>` | hide, or make visible, elements specified by a list of ids.

  You can specify any mix of of these subactions.
  Details

  `<confirm>` | <confirm> A message </confirm> A message can include show name="varname" A confirmation box will popup, displaying `A message`. If you click on `cancel`, then the change will not occur. This allows you to double check before making crucial changes. Note: as an alternative to <confirm>, you can use a `confirm()` in an IF.

- `<CONFIRM>` causes a confirmation box as soon as the input element is changed.
- `confirm()`is asked after the form is submitted (say, in a `<DO>` action invoked by the form).. In fact, to be really pesty you can use both!
  `<alert>`
  <alert fade="1" seconds="nSec" where="towhere"> A message </alert>
  Display a message in one of several fashions.
  - `A message`: what is displayed.
  - A message can include show name="varname"
  - for all occurrences of `this.value`, the value attribute (of this element) is used
  - for all occurrences of `this.set`, the set attribute (of this element) is used
  - `where`: specify where to display the message. You can specify one, two, or all three of the following:
  - `where="ALERT"` : write to javasript alert
  - `where="STATUS"` :write to _controlStatus area -- this is a box toward the bottom of the browser screen.
  - `where="DATAMESSAGE"` : write to dataMessage area -- this is a transient & non-movable box toward the bottom of the screen. When you click on this box, it will disappear. You can use `seconds` and `fade` to control how temporary this message is.
  - `seconds="nsec"` : only used if `DATAMESSAGE` is specified. after nsec seconds, the dataMessage box will disappear. If is not specified, the dataMessage box will go away when clicked.
  - `fade="1"` If specified, the font color will fade away, and then the dataMessage box will disappear.
    Only used if `DATAMESSAGE` is specified and seconds="nsec" is specified.
  Note: the `this.` variables refer to attributes of the element that this `<change>` is associated with.
  Example:

  If the following attributes are specified: | <attributes> <anId1> <change> < alert > This will set the value of myVar1 to this.value </alert> </change> </anId1> </attributes>
  And the following is in a `FORM` | <input name="myVar1" value="3" type="checkbox" id="anId1" />
  Then ... | when the check box is hit, an alert will appear that reads `This will set the value of myVar1 to 3`

  `<set>`
  <set nowait="1"> varname=avalue </set>
  Set a control, or (by default) a general variable.
  This is an alternative to specifying a simple input element in a `FORM` (such as `<input type="checkbox" >`). It can be used to specify several values to change (say, on one button push): by using several <SET> statements, or by using semi-colons to specify several `varname=avalue` pairs.

  Note that `<set>` complements the values changed expliticily by an input element in a form. ,

  That is, when a form is submited: | the `<set>` will be done, the variable specified in the input element will be changed.

  Special features:

  - To suppress the variables and value specified in the input element, (and have only the `<set>` be used for modifying variables), use `name="."` in the `input` element.
  - if `nowait="1"` is specified in the `<set>`, then control variables will immediately be saved (a submit is not required to save their new values).
    However, this only works with control variables: it will not work with general variables.

  Caution: if you use a `<set>` outside of a `<change>`, then the `value` of the element will be changed to the verbatim contents of this `<set>`.
  So be careful to use `<set>` within a `<change>`!

  `<display>`
  <display type="howdo">idList </display>
  Hide/display an element, such as a `<div>` or a `<span>`. It is similar to <display> action.
  `divList`: a space delimited list of IDS for elements. Each element in this list will be made invisible, made visible, or toggled (between visible and invisble)
  - `howdo`
  - `howdo="NONE"`: make invisible.
  - `howdo="BLOCK"`: make visible (as a block element).
  - `howdo="INLINE"`: make visible (as an inline element).
  - `howdo="TOGGLE"`: toggle. This is the default (if `howdo` is not specified)
  Note: <display> works by changing the `display` CSS elements. Thus, to set a default display type you could use (in the element) `style="display:none"` (to start invisible) or `style="display:block"` (to start visible).
  The If modifier
  In <confirm>, <alert>, and <display> you can insert an "if" attribute.

  `if="logical condition"` If the "logical condition" evaulates to false, the sub-action is skipped.

  The "logical condition" has a syntax of:`var1 cond var2`
  where

- `var1` and `var2` : general or control variable
- `cond` : one of `EQ NE GE GT LE` or `LT`

  #### Special features:

  - If var1 (or var2) is `this.value`, the value attribute (of this element) is used
  - If var1 (or var2) is `this.set`, the set attribute (of this element) is used
  So what is the difference? `this.set` refers to the value field before the input-field was clicked (or otherwise changed), while `this.value` refers to the value afterwards. Often these are the same, but sometimes they aren't. In other words, this is feature is still rough; you will have to play with it to make sure it is doing what you want.

  Examples:
  <noPets> <change> <confirm if="suVersion eq 1"> You are using version 1. Are you sure you want to skip this step? </confirm> </change> </noPets> <idAdvanceYes> <change> <confirm if="nowround.g eq computedRound.c" > If you select this, the next round will start. However, the current round (<read var="nowround.g" />) is incomplete. Are you sure you want to do this? </confirm> </change> </idAdvanceYes> <amazing1> <change> <alert where="status datamessage">You made the amazing choice </alert> <set> wantAmazing=1 </set> </change> </amazing1> <boring> <change> <alert fade="1" seconds="10" where="status datamessage">You made the amazing choice </alert> </change> </boring1> <useG> <change> <display if="this.value eq 1" type="block"> useGf1 useGf1a </display> <display if="this.value eq 2" type="block"> useGf2 useGf2a </display> </change> </useG>
  <Do>
  `<Do>` is used to specify a task-list. As described in detail below, these dSurvey tasks can:
  - save a variable to the server (where it can be retrieved by clients)
  - read "session specific" XML data files from the server
  - specify "client-accessible" (hence session specific) XML data files to write to the server
  `DO` can be invoked in several ways:
  - By including a doTasks="doName" attribute in an element in the <PANEL > section of the control panel program.
  - By including a <submit do="doname"> in a `<FORM>`
  - By specifying a <DO name="doname" > in the `<INIT>` section

  A `<Do>` contains a number of tasks (a task-list), all of which are specified using XML elements. Some of these tasks may contain other elements, or may expect attributes.

  Basic syntax:

  <DO name="aname" message="descriptive message"> <aTask> </aTask> ... <aTask> </aTask>
  where:

  `name:` | required. `do` specifies the name of a `<do>` action. Thus, you can have several different <Do>, each with a different name value. These can be invoked at different times.
  `message:` | Optional: the `title` used for the current-status block (the far-right block of the task history bar). This is `message` is displayed on `mouseOver` of this block. Note that in the element that invokes this `<do>` (using a `doTasks` attribute), you can specify a summary attribute. This `summary` attribute specifies a message to display in the task-bar (using highlighted text).
  `aTask` | The task-list is simply the one or more (typically more) `<atask .. > ... </atask>` specified in a `<do>`. Each `atask` must be one of the `DO tasks` that are listed below. For example: tasks that save variables to the server, and tasks that match reference data to participants. Tasks are processed in order of appearance. Some tasks are meant to be specified just once per task-list, others can be specified multiple times in a task-list.

  The DO tasks
  Currently, the following tasks are supported:

  <alert> | Write a message
  <checkClients> | Query server about participant's status
  <checkScenarioList> | check scenario list (for start of new scenario)
  <assignRefID /> | Assign a "reference id" to current participants
  <downloadData /> | Retrieve archive data from the server and save to local hard drive, or to workData
  <display > | Hide, or display, HTML elements
  <fromResults> | Use results data to create user, or general data
  <focus> | Set the browser focus to an area
  <getParams> | Retrieve a session-specific XML data file, store results in control panel databases
  <getParticipants /> | Retrieve the current participants for this session
  <getSubmitted /> | getSubmitted: get the server's submitted data archive, and store in submittedData and/or save to a local file
  <getVar> | getVar: Retrieve one, or several, variables from the server
  <if> ... </if> | conditional execution of a do action
  <join /> | Allow, or disallow, new participants joining this session
  <loadScenario /> | Load parameters specified in a scenario file
  <loadSnapshot /> | Load session specific parameters that were previously saved using a takeSnapshot.
  <monitor /> | Process all `<monitor>`
  <next_task /> | Modify what the Next task button does.
  <postVar> | Set one, or several, variables on the server
  <postCAP> | Create a client-accessible XML data file on the server.
  <readLocal> | retrieve, from the local hard drive, an XML data file.
  <reset> | reset the GENERAL, USERS, SERVER, CONTROL, and/or REFERENCE control-panel databases
  <recoverParams /> | recover parameters from snapshot and CAP files
  <resolveReference /> | add variables from Reference Variable to User Variables
  <saveData> | write a current control-panel dataset to a local file (using an XML like format)
  <set> | create a GENERAL or CONTROL variable, and call custom functions.
  <show var="varname" /> | replace with current value of a variable
  <stop /> | stop processing this DO.
  <takeSnapshot /> | Save a snapshot of current control panel databases
  <updateSubmitted /> | move the `current` submitted data to the end of the all-rounds submitted data
  <updateDiv /> | change the contents of an element on the control panel screen
  <uploadData> | post a current control-panel dataset to an archive on the server (using an XML like format)

  Note that `if`, `quit`, and `stop` are a bit different: they are logical elements that control what tasks will be processed.

  alert: write a message
  Syntax:
  <alert where="howShow" seconds="nsec" fade="1" show="n" autoClose="0" literal="1" > a message </alert>
  `howShow` can contain one, or more, of the following words: ALERT, STATUS, STATUS_INTER, SUGGEST, TASKBAR, DATAMESSAGE, and MOVEBOX. where..
- `where`: where to display the message
- `seconds, fade`, and autoClose: used by `where="DATAMESSAGE"` (controls how the dataMessage box is displayed
- `open`: used by `where="SUGGEST"` (controls if suggestion box is displayed)
- `literal`: used mostly with `where="STATUS"`. If `literal="1"` is specified, then the message will be used as is -- `<show>` special tagnames will not be processed. However, all `html` content will be displayed. Thus, `literal` is used if you want to display some moderately complex HTML (say, containing a `<a>` link), at the price of giving up the ability to dynamically display current variable values).

  #### Details on `where`

  - `where="ALERT"`: `a message` written in a javascript alert box
  - `where="STATUS"` :write to _controlStatus area -- this is a box toward the bottom of the browser screen. This is a final message. Note: `STATUS_FINAL` is a synonym for `STATUS`
  - `where="STATUS_INTER"` : similar to STATUS, but this will be an intermediate message.
  - `where="TASKBAR"` : `a message` is written to the task history bar. The task-history bar is a small box (1 line high) at the top of the page, with a color background.
  - `where="SUGGEST"` : `a message` is written to the suggestion box. You can view the suggestion box by clicking on the Suggestions ... button at the top of the screen.
  - `show="1"` : display the `suggestion box` (make it visible if it currently hidden)
  - `show="2"` : display the `suggestion box`, and move focus to it
  - `where="DATAMESSAGE"` : `a message` is written to the data-message box (a small box toward screen bottom, that will disappear when clicked on) If `dataMessage` is specified, the `autoClose="0"`, `seconds="nsec"` and `fade="1"` attributes can also be specified:
  - `seconds="nsec"` :after nsec seconds, the dataMessage box will disappear. If is not specified, the dataMessage box will go away when clicked.
  - `fade="1"` If specified, the font color will fade away, and then the dataMessage box will disappear.
  - `autoClose="0"`: If specified, the data-message box will not be closed when clicked on.
    Instead, to close the box one must click on a small `x` (in the upper left corner).
  - `where="MOVEBOX"` : `a message` is written to a moveable box. This box, which starts on the left side of the screen, can be resized and move. It is non-transient -- you must close it if you don't want to see it.
  - `where="'other_id"` : if not one of the above, replace the contents of an element with id of "other_id" (if such an element exists)

  #### a message

  The `a message` can contain text. Depending on the value of `where` and `literal`, the message can contain:
- HTML markup.
- `<show name="varname" />` elements: the the current value of `varname` will be displayed. In particular:
- For `dataMessage` and `moveBox`: `a message` can contain complex HTML (with HTML elements nested inside of HTML elements)
- For the others (`alert`, `status`, etc.): you should keep the message simple (i.e.; no HTML markup).
  Exception: if you specify `literal="1"`, you can display complex HTML (but `<show>` will not be processed).
- Hint: it can be useful to include links, in the status messages -- say, to return to the tasks table. The links noted in <next_task> are useful!
  Example:
  <alert where="STATUS" literal="1"> <br/> <a title="Return to tasks table" href="#_customTasks1_">(back)</a> <alert>

  #### Intermediate messages

  The STATUS_INTER option creates an intermediate message. The STATUS option creates a `final` messages.
  How do these differ?
  - Final : `Final` messages are always displayed in the `status messages` area.
  - Intermediate : `Intermediate` messages are displayed only when the `vuHistory - toggle_display_of_the_intermediate-actions` generic control panel option is set. Note that this can be toggled -- the messages are always there, but they are only displayed when display of intermediate status messages is enabled.
  Note that both kinds of messages will be written to the `history of prior actions` area.

  Notes on `suggest`

- `suggest` is designed for longer messages, that may include html tags (such as <b>).
- The `show` attribute of `<alert>` is only used with `SUGGEST`
- Special syntax: if the content (between the `<alert >` and the `</alert>`) consists of two `<div>` elements, and there is no text before the first `<div>`, then
  The content will be split into two parts.
  1. The first part (the contents of the first `<div>`) will be displayed,
  2. A More ... link will be displayed
  3. The second part will not be displayed.
  4. When the More ... link is clicked, the second part will be displayed.
  Note that the contents of either `<div>` can be as complex as you desire -- what matters is that the `<alert >` just has two children (the two `<div>`s), and that there be no text before the first `<div>`.
  checkClients: query server on participant's current status
  This will query the server on the status of all participants. It will also do a few tests to determine the status of all active participants.
  Syntax:
  <checkClients statusVar="cVar" statusMessage="cMessage" statusSummary="sSummary" serverVars="varlist" > <test> testEquation </test> <drop> dropEquation </drop> <repeat close="what"> Repeat message </repeat> </checkClients >
  - `statusVar="cVar"` : Optional, `cvar` should be the name of a control variable to create. It will contain the results of the `<test>`.
    If `<test>` is not specified, `cVar` will equal 0.
  - `statusMessage="cMessage" "` Optional, `sSummary` should be the name of a control variable to create. It will contain a table describing current status (# of participants, how many are dropped, and how many pass the test), which can be displayed using a `<show>`
  - `statusSummary="sSummary" "` Optional, `sSummary` should be the name of a control variable to create. It will contain a table summarizing the distribution of status and message variables, with a count and a list (by NAME) of participants in each combination of these two variables's values.
    The table can be displayed by using the `statusSummary` variable in a `<show>`
  - `serverVars="varlist"`: Optional. If speciifed, varlist should be a space delimted list of variables on the server. These are variables set by the control panel, and saved on the server (i.e.; variables that participants QUERY for). If you specify `serverVars`, and a `statusSummary`, the values of these server variables will be displayed as part of the summary.
  - `<drop>`: the `dropEquation` is used to determine which participants are ignored
  - `<test>`: the `testEquation` is used to compute the `statusVar`.
  - `<repeat close="which" >`: Optional. If specified, a button will be added to the `statusMessage`, clicking the button will recall the task that contains this `checkClients`. The `Repeat message` will be used as the text of this button.

    `close="which"` is optional. If specified, a `Close` button is displayed. What this button does depends on the value of `which`
  - `close="datamessage"`: the `dataMessage` box is closed (this is used with an `<alert where="datamessage" .. >`.
  - `close="movebox"`: the `moveBox` box is closed (this is used with an `<alert where="movebox" .. >`.

    Note that if you display the `statusMessage` using an `<alert where="datamessage">`, be sure to include a `autoClose="0"` attribute in the `<alert>`. (or, consider using the the `moveBox`, which is designed for semi-transient information).

  ### `testEquation` and `dropEquation`

  If `statusVar` is specified, the `testEquation` and `dropEquation` are used to `test` the status of all the clients (if `statusVar` is not specified, `testEquation` and `dropEquation` are ignored).

  If specified, the `testEquation` and `dropEquation` should be valid dSurvey equations. Each equation should evaluate to a `0` or a `1`. As with all dSurvey equations: strings should be `'quoted'`, control and other variables can be specified, and `$+` should be used to concatenate strings and variables. Often, these equations will contain logical operators. And typically, they will use the `_stateVar` and `_descVar` participant specific, server supplied, variable.

  Example... | <checkClients statusVar="sStatus" statusMessage="sMessage" > <drop> _stateVar lt nowRound.g </drop > <test> _descVar eq 'waitingToAdvance' </test > </checkClients >
  ... | Note the use of `'waitingToAdvance'` (in the `<test>`) to denote a literal string.

  #### Using DROP and TEST

  When `statusVar` is specified, `checkClients` computes the `statusVar` by examining status information (as retrieved from the server) for each participant.
  1. If `<drop>` is specified: the `dropEquation` is used to determine if the participant should be dropped. If the `logicalEquation` evaulates to `1` -- the participant is dropped. That is: his information is not used to determine the value of `statusVar`.
  2. For all non-dropped participants: the `testEquation` is examined.
     It the value of the `testEquation` equals `0`, then `statusVar` is set to `0`
  Thus, `statusVar` will be one only if the `testEquation` for all `non-dropped` participants equals `1`

  You can use the value of the `statusVar` to control which actions are done after the `checkClients`.

  For example... | <if value="sStatus eq 1"> <alert where="dataMessage">Everyone responded -- advance to the next round! </alert> </if> <if value="sStatus ne 1 "> <alert where="dataMessage">Still waiting for participants to respond ... </alert> </if>

  The `dropEquation` and `testEquation` can refer to dSurvey variables. In addtion, two special variables can be used, whose values will be participant specific:
  - `_stateVar`: the value of the particiant's `state` variable.
  - `_descVar`: the value of the particiant's `desc` variable.

  > For example, you can use the `_stateVar` to `drop` all particpants who have left the session, and then use the `descVar` to see if all remaining participants have complete the current round.

  Note that if `<test>` is not specified, the `statusVar` will always be set to `0` (`<drop>` is ignored).

  In any event, the `sMessage` control variable (if specified) will contain a short summary of the clients' status -- which can then be displayed. For example, one could use (after the `<checkClients>)`:
  <alert where="datamessage"> <show var="sMessage.c" /> </alert>

  Note: | the `statusSummary` variable (if specified) is an alternative means of displaying the status of the clients. It does not use the `testEquation` and `dropEquation`, so it is less customizable. But it does present information in a compact fashion, which might be good enough.

  #### How are the `_stateVar` and `_descVar` variables determined?

  Both can be set in the SPEC file -- by specifying attributes in a `<serverVar>` under a <query>
  - `_stateVar`: set by a `stateVar` attribute
  - `_descVar` : set by a `desc` (or `descVar`) attribute
  For example:
  (in a startARound section ) <notify value="atRound" stateVar="nowRound" /> (in an afterResponsesAndWait section ) ..... <query saveVar="askRound"> <serverVar var="Round" desc="waitingToAdvance" /> <if value="askRound gt nowRound" > <goto section="READY_FOR_NEXT" /> </if> </query>
  In the above, when a new round first starts the pariticipant notifies the server that he is now at round `nowRound` (the value of the `nowRound` variable is sent to the server).
  Then, after the participant provides respones, and is ready to go to the next round -- he repeatedly checks to see if he should advance to a new round -- and in each check he tells the server that is `waitingToAdvance`

  Notes:
  - to see the individual status of all participants, you can use the UserStatus link at the top of the control panel.
  checkScenarioList: check scenario list: start of a new scenario?
  Syntax:
  <checkScenarioList var="roundVar" /> <checkScenarioList show="1" >A message </checkScenarioList > <checkScenarioList check="1" >A message </checkScenarioList > <checkScenarioList check="1" var="roundVar" >A message </checkScenarioList >
  where...
  - `var="roundVar"`: Optional. If specified, it should be a number or (more typically) the name of a variable that contains the round. This round value will be compared against the rounds specified when the scenarioList was created. If not specified, `nowRound.g` is used.
  - `show="1"`: If specified, the Scenarios box will be displayed, with `A message` at the top. `A message` can contain HTML, but not dSurvey elements such as `<show>`.
    If `show="1"` is specified, `roundVar` and `check="1"` are ignored.
  - `check="1"`: If specified, a moveable box will be displayed that contains a link to load a scenario. The `A message` is also displayed. `A message` can contain HTML, but not dSurvey elements such as `<show>`.
  `checkScenarioList` is used with the currently active `scenarioList` -- that you have created (or retrieved) using the Scenarios option at the top of the control panel). If you have not constructed a `scenarioList`, `checkScenarioList` will do nothing.

  `<checkScenarioList>` should be called before `<postCap>`, and after the round variable (i.e.;`nowRound.g`) has been updated.

  If (at the moment `<checkScenarioList>` is invoked) the value of `round` variable (i.e.; `nowRound.g`) equals the first round in a scenario (that appears in the `scenarioList`) then a javascript confirmation box will ask if you want to load the associated scenario. If you chose to, the scenario will be loaded. That is: the general parameters specified in the scenario will be used in a subsequent `postCap`.

  If `check="1"` is specified, a moveable box is displayed (instead of a javascript confirmation box). A major advantage of using `check="1"` is that this moveable box, although it contains a `continue` button, does not monopolize focus.Thus, when the moveable box pops up, the administrator can then select options on the control panel; such as setting `demo` variable using a `checkbox`, and then clicking on the `continue` button in this moveable box.

  In contrast, when a javascript confirmation box is used, focus can not be shifted from the confirmation box (you must accept or cancel). Thus, it is difficult to make changes before deciding to load the scenario. This can be a hassle, requiring more complex scenarioLists or more attention on the part of the administrator.

  Note that if `show="1"` is specified, this test is not attempted. Instead, the scenarioList is displayed, with color highlighting used to signify which scenario is active. One can then chose a scenario to load (by clicking on a `load` button) -- say, when the new round is the first round of scenario.
  Useful trick: loading a scenario at startup
  When administering a complex session (say, with several rounds of several different treatments), it can be convenient to create scenarios and scenario lists.
  For example, you can use the Create a scenario file for an instrument administrative action to create scenario, or scenarioLists, for an instrument.
  In particular, loading a scenario list as soon as the session starts can save hassles (you specify the scenarioList at your leisure, rather than in the hectic moments before participants show up).

  An easy way to do this is to specify an initialization task that uses the `show="1"` attribute with `<checkParticpantList>`.

  Example: | First, create a task: <do name="askScenario" > <checkParticipantList show="1" > Do you want to load a scenario, or a scenario list?') </checkParticipantList> </do> Then, specify an initialization action. For example, if you are using the generic control panel, include the following in the <SUB name="_initDo" > section: <do name="askScenario" />

  Useful trick: NOWROUND_SCENARIO
  Whenever a new scenario is loaded, the `NOWROUND_SCENARIO` GENERAL variable is set to `0`.
  Often, it is useful to increment NOWROUND_SCENARIO whenever a new round starts. Thus, `NOWROUND_SCENARIO` can be used to count the number of rounds this treatment (scenario) has been running.

  For example: when `NOWROUND_SCENARIO` equals `1` (say, after the SPEC file augments `NOWROUND_SCENARIO` when a new round first starts), a set of random values (say, as produced with `dsvyRandom()`) can be replicated. This is a nice way of maintaining the same values across the same relative round in different treatments.
  Advanced option: using <header >
  When `check="1"` is specifc (and `show` is not used), a generic message is displayed in the header bar of the moveable box. This generic header message contains three buttons:
- load the next scenario, and go to the next round
- do NOT load the next scenario, and go to the next round
- do NOT load the next scenario, and do NOT go to the next round However, you can customize this message by specifying a
  <header replace="1" > header message </header> ....
  inside of the `checkScenarioList` container.

- If `replace="1"`, the `header message` will replace the generic header message
- Otherwise, the `header message` will appended to the end of the generic header message If you use `replace="1"`, we highly recommend using the following special codes in your `header message` -- they will be replaced with the following buttons.
- `[!LOAD]` is replaced with a
  (to load the next scenario, and go to the next round)
- `[!SKIP]` is replaced with a
  (go to the next round, without loading the next scenario)
- `[!STOP]` is replaced with a
  (do NOT go to next round, and do NOT load next scenario) Note that `!xxxx` codes are inside of square brackets (`[ and ]` )
  assignRefID: assign a "reference id" to current participants.
  Syntax:
  <assignRefID reset="0" />
  This should be called after a parameter file containing REFERENCE information has been read (using getParams), and current participants have been retrieved (using getParticipants). That is: assignRefID will not retrieve the participant list from the server (it will use the results of the most recent participant list (that was retrieved using `<getPaticipants>`).

  assignRefID is usually called before <resolveReference />

  `reset="0"` is optional. If specified, then current-participants that have been assigned a REFID will not be assigned a (potentially different) refid. The default is `reset="1"` : rewrite the REFID of all participants.

  Reference ids point to a row in the REFERENCE data. The algorithim used to assign a reference ID to a user is a function of the session specific HOW_ASSIGN variable (as set in the session descriptor file).

  downloadData: retrieve archive data from the server and save to local hard drive, or to workData
  Several kinds of "archive" datasets (for this session) can be retrieved from the server: General, Users, Participants, History, or Results.
  The retrieved archive dataset will then be saved to the local (the computer running the control panel) hard drive as a CSV or an XML file, or saved to the `workData` control panel database.
  - See uploadData for the details on adding information from the control panel to these server-side archive datasets; and savingResults.htm for even further discussion.
  - Downloading `submittedData` is a bit different, since submittedData is "built" by clients rather than by the administrator. Thus, to download submitted data, use getSubmitted.
  - Hint: Use `uploadData` to build a dataset (saved as `custom`) that contains all the variables you might want to use in further analysis. And then (at the end of the session) use `downloadData` to retrieve it.
  Syntax:
  <downloadData type="atype" file="localFile.xml" name="descriptive_word" CSV="options" round="roundlist" workData="1" popup="1" />
  where...
  - `type:` either`GENERAL, USERS, PARTICIPANTS, HISTORY,` or `RESULTS`. Or, `CUSTOM`
  - `file:` optional. If specified, the name of the file to save the submitted data to. If not specified, `atype+Data.xml` or `atype+Data.csv`, is used (i.e.; `generalData.xml`).
    Actually, a file save box will popup, with `localFile.xml` (or whatever is specified) as the default choice.
    Saving the file requires you to use this popup (javascript does not work directly with local files, so a server-based hack is used that fires up this popup).
    To suppress saving to a local file, use `file="0"`.
  - `popup:` If `popup="1"` is specified, than display the contents of the file in a popup window.
    Hint: Since saving these server archive datasets to local files uses a convoluted process (due to javascript security constraints), sometimes it is quicker & safer to display the contents of a database in a popup window, rather than saving to a file. You can then save the popup window to a file using the browsers `save page` option (or you cut and paste the popup window's contents to a file).
  - `rounds`: optional. If not specified, then only the current round's data data is saved (uses the `nowround.g` variable). If specified, should be a space delimited list of round numbers. Or variables (control or general) that contain a round number (such as nowround.g).

    Shortcut: use a `rounds="*"` to save data from all rounds.

  - CSV:: optional. If specified, save as a CSV (comma seperated value) file, and not as an XML file.
    CSV can contain a list of options, that control how the CSV file is written. The basic values are:
    - `CSV="0"` : Do not save as CSV. This is the default.
    - `CSV="1"` : Save as CSV. The first line will contain the variable names.
    Or, you can specify several options in a space delimited list. The options are:
    - `NOHEADER`: do not include variables names (as the first line). By default, include variable names..
    - `DESC`: include a short description of the data (session name and time) as the first line (the 2nd line will contain the variables names). By default, do not include descriptive information.
    - `NOQUOTE`: do not quote (in " ") non-numeric values. By default, quote all non-numeric values.
    - `NODEFAULTS`: suppress output of default values. That is: default records (that do not refer to a participant in a round) will be suppressed. By default, include these "default" records
    - `MISS=c` : where c is any character. Use this `c` for missing values. The default is a 0 length string.
    - `EXPAND=m` : where m is 0, 1, or 2. If non-zero, then expand array variables (into seperate variables).
      This will be done if:
    - `EXPAND=1` or `EXPAND=2` is specified (the default is 0)
    - The variable is from the `GENERAL` database
    - The value of this variable contains commas If these conditions are satisfied than for each element in the array, a new variable is created (and will be assigned the appropriate value).

      To create the new variable names, there are two formats: |

    - `EXPAND=1` (aname_i_ syntax):

      Example: if a `COST` GENERAL variable has a value of `,1,100,44`, the following variables will be created:

    - `COST_0_` (value=''),
    - `COST_1_` (value=1),
    - `COST_2_` (value=100),
    - and `COST_3_` (value=44).
    - `EXPAND=2` : (aname[i] syntax):
      For example: instead of `COST_1` used as a variable name, `COST[1]` is used.
    Examples:
    CSV="1" CSV="NOHEADER NODEFAULTS" CSV="DESC NOQUOTE MISS=." CSV="EXPAND=1 NODEFAULTS "

  - `name:`: optional. Only used with `CUSTOM.` The name of this "custom" database (used by the server to determine where to store the data). It should match the "name" used in <uploadData>.
  - `workdata="1"` : optional. If specified, then the contents of the retrieved file will be saved to the `workData` control-panel dataset.
    Reminder: you can view the `workData` control-panel-dataset by using the Data option at the top of the control-panel screen.

  #### Notes:

- these archive datasets must be explicitily built, typically by using the <uploadData> task.
- current values of control panel databases will not be effected by downloadData.
- `<getParticipants>` is an alternative means for retrieving information currentParticipants; however it is more "active"
  display: show, or hide, HTML
  `display` is used to hide, or make visible, elements specified by a list of ids. It is similar to the display of the change attribute.
  If you want to change the contents of an element, or change an element's style, consider using <updateDiv>.

  Syntax:
  <display echo="1" type="howdo" clear="1" > idList </display>
  where...
- `echo="1"`: optional. if `echo="1"` then a short message is written to the status area (noting what display areas have been changed)
- `clear="1"`: if `clear="1"` is specified, than the contents of the element (say, the `innerHTML`) will be erased
- `howdo`
- `howdo="NONE"`: make invisible.
- `howdo="BLOCK"`: make visible (as a block element).
- `howdo="INLINE"`: make visible (as an inline element).
- `howdo="TOGGLE"`: toggle. This is the default (if `howdo` is not specified)
- `idList`
  List of `ids` to modify.
  There are several special `ids`
- `_formArea`: the area where forms (with input fields, etc) are displayed
- `_controlStatus`: where status information is written
- `_controlStatusHistory`: where the status-history information is written
- `_variousRecent`: the Last action information-bars

  The next three are used in the generic control panel.

- `_optionsTables1`: the `pre-session tasks` and `generic` tables
- `_showCustomTasks1`: the `custom tasks` table
- `_customTasks1` : more `custom tasks` (that are always displayed)
  getVar: Retrieve one, or several, variables from the server
  Syntax:
  <getVar delim="x" default="avalue" > varlist </getVar>
  where...
  - `varlist:` a comma delimited list of cname=sname pairs, or just sname.
    Example:
    cround=nowround cround=nowround nowversion nowtask
  - `delim:` optional. Use this to seperate returned values. Only necessary if a return value may contain a comma (in which case "x" should be a character that will never appear in a server variable)
  - `default="avalue"`: optional. If the server variable does not exist, return `avalue`. If not specified, an empty string is returned.
  1. Each of the "sname" server variables will be read.
  2. The values will be stored as "server variables" (in the serverVariables array) using the respective snames.
  3. If you specify a "cname=", then the value will ALSO be stored as a control variable (in the controlVars array), using cname.
  Example:
  If the nowround server variable is 12, then
    `cround=nowround`
    will set create a control variable named `cround` with a value of 12, and a server variable named `nowround`with a value of 12.

    Note: by creating a server variable we mean storing a variable in the serverVars array of this control panel.
    That is, it does not mean saving a variable on the server" (see postVar).

  fromResults: extract data from results Data and use it to modify the userData and generalData
  Syntax:
  <fromResults< varname.g = rVar </fromResults> <fromResults< varname.u = rVar </fromResults>
  where...
- `varname.g` : a general variable will be created. The value is pulled from the * id record of the resultsData database, using the rVar variable.
- `varname.u`: a user variable will be created for all current clients (as specified in the currentParticipants control panel database). The value is pulled from the client-specificd records of the resultsData database, using the rVar variable.
- The details ...

  focus: set the browser focus to a desired location
  Syntax:
  <focus where="aName" /<
  `aName` should refer to the `name` of an `<input>` element, or to a `<a name="aName>` element, that exists in the `<panel>` section.
  You can also use the <next_task> task to set the focus

  The following generic names that you might find useful:
  - `0` : do not change the focus
  - `_top` : scroll to top of page
  - The next several assumes the instrument's control panel is built from the generic dSurvey control panel.
  - `_topBar_` : the utilities bar (top of the page)
  - `_taskHistory_` : the task history bar (near the top of the screen)
  - `_customTasks1_` : the top of the Session tasks table
  - `_customTasks2_` : the 2nd set of custom tasks (below _customTasks1_)
  - `_statusDisplay_`: The status/results area
  - `_formDisplay_` : The form entry area
  getParams: Retrieve a session-specific XML data file, store results in control panel databases
  Syntax:
  <getParams userVars="uVars" generalVars="gVars" refVars="rVars" noGet="aList" > xmlFile </getParams>
  where:
  - `xmlFile` : a "session specific" XML data file in the session-specific directory. This must have the "session specific data file" syntax (see below).
  - `gVars` : Optional. a variable name used to save the "general" variables read from this file. This variable name can be used as a shorthand in postCAP.
  - `uVars` : Optional. a variable name used to save the "user" variables read from this file. This variable name can be used as a shorthand in postCAP.
  - `rVars` : Optional. a variable name used to save the "reference" variables read from this file. This variable name can be used as a shorthand in postCAP.
    Note that gVars, uVars, and rVars will be saved as control variables. But do not prepend or append anything .
    Example: `generalVars="sessGvars"`
  - `noGet= Optional.` `alist` should be a space delimited string that can contain the following: `USERS REFERENCE GENERAL.` This is used to suppress reading of the respective section. Thus, `noGet="USERS GENERAL"` means just read the REFERENCE section.
    If not specified, read all 3 sections.
  You can specify many different getParams. The variables (general, reference, and user) will be read, and saved additively. If a later file contains variables also specified in the earlier file, the earlier values will be overwritten.

  #### Notes on storage:

  - general variables are saved in the `generalVars` control-panel database. Hence, a `"costFactor"` variable would be saved as `generalVars['COSTFACTOR']` `generalVars['$VARS']` contains a list of all the general variables.

    Actually, a 3 element array is saved to generalVars['VARNAME']:

  - `generalVars['VARNAME'][0]` : a value of `1` if this should be treated as an array
  - `generalVars['VARNAME'][1]` : value. If an array, values are always seperated by a comma. Note that the value is always a string (not an array)
  - `generalVars['VARNAME'][2]` : uncapitalized version of the varname You can use `readGeneralVar()` and `getVarInfo()` to work with generalVars.

  - user variables are saved in the `userData` control-panel database. Hence, for userId of 35, a "income" variable would be saved as `userData['35']['INCOME']` (note the uppercase is always used in object references).
    `userData['$VARLOOKUP']` is an object used to identify if an variable exists: i.e.; `userData['$VARLOOKUP']['COST']=1` if `COST`variable exists.
    Otherwise, undefined
  - `userData['$IDS']` contains a list of all the ids.
  - `userData['$VARS']` is an array, with each element one of the variables

  - reference variables are saved in the `refData` control-panel database. Hence, for refId of 12, a "group1" variable would be saved as `refData['12']['group1']`
  - `refData['$VARLOOKUP']` is an objecct used to identify if an variable exists: i.e.; `refData['$VARLOOKUP']['COST']=1` if "COST" variable exists Otherwise, undefined
  - `refData['$IDS']` contains a list of all the ids.
  - `refData['$VARS']` is an array, with each element one of the variables
  getParticipants : Retrieve the current participants for this session
  `getParticipants` will retrieve (from the server) information on current participants for this session. It will then save this information either to a file (on the local computer), or to the `currentParticipants` control-panel database.
  Syntax:
  <getParticipants file="filename.xml" /> or... <getParticipants length="lenVarname" file="0" />
  where:
  - `file`
  - `file="fname" not specified`. The "suggested" file name (on local hard drive) will be `currentParticipants.xml`.
  - `file="fname"` : Optional. Name of file (on local hard drive) to "suggest"
  - `0`: do NOT create a file. Instead, update the `currentParticipants` database (say, for use by a `<message>` in <postCap>).
  - `length="lenVarname"`. Optional (only used if `file="0"`. If specified, save the number of current participants in a `lenVarname` control variable. You can then reference this later (say, by using `<show var="lenVarame.c" />` in an `<alert >`).
  The participant information includes the NAME, NICKNAME, and CONTACT for each client, and his `client-id`. The `client-id` is a unique number for each client (participant). It may be assigned by the server, or generated by the client before joining the session. See the client-side assignation section of generateParameters.htm for more details

  Notes:

- If `file="0"` is not specified, `<getParticipants>` will not change `currentParticipants`
- You can also use downloadData to copy from (and to) a server-side archive: without effecting the values of control panel databases.
  getSubmitted: get the server's submitted data archive, and store in submittedData or to a local file
  You can get the entire archive, or just a selected round (i.e.; the current round).
- to retrieve user, results, participant, and general data; see downloadData.
- as of this writing, there is no way to download submitted data without refreshing the submittedData control panel database.
- `getSubmitted` is often used to retrieve submitted data for processing. See savingResults.htm for details.
  Syntax:
  <getSubmitted file="localFile.xml" csv="options" rounds="roundlist" all="1" getCurrent="1"/>
  where:
  - `file`: optional. If specified, the name of the file to save the submitted data to. If not specified, `submittedData.xml` is used.
    Actually, a file save box will popup, with `localFile.xml` (or whatever is specified) as the default choice. Saving the file requires you to use this popup (javascript does not work directly with local files, so a server-based hack is used that fires up this popup).

    Special features | `file="."` if `file="."`, then do not save to local drive. This is used to update the submittedData control panel database. If file="." is used,

  - if `getCurrent="1"` is not used, all data in the all-rounds archive is saved to submittedData (rounds and all="1" are ignored).
  - if `getCurrent="1"` is used, data in the current-round archive is saved to submittedData (rounds and all="1" are ignored).

  - `csv`: optional. If specified, then display the submitted data in CSV format in a popup window.
    (Note: this uses a syntax similar to the CSV option of downloadData).

    CSV can contain a list of options, that control how the CSV file is written. The basic values are:

    - `CSV="0"` : Do not save as CSV. This is the default.
    - `CSV="1"` : Save as CSV. The first line will contain the variable names.
    Or, you can specify several options in a space delimited list. The options are:
    - `NOHEADER`: do not include variables names (as the first line). By default, include variable names..
    - `DESC`: include a short description of the data (session name and time) as the first line (the 2nd line will contain the variables names). By default, do not include descriptive information.
    - `NOQUOTE`: do not quote (in " ") non-numeric values. By default, quote all non-numeric values.
    - `MISS=c` : where c is any character. Use this `c` for missing values. The default is a 0 length string.
    Examples:
    CSV="1" CSV="NOHEADER NODEFAULTS" CSV="DESC NOQUOTE MISS=."
  - `rounds`: optional. If not specified, then only the current round's data (as specified in the `nowround.g` variable) is saved to `submittedData` control-panel database, and/or to the `file`.
    If specified, should be a space delimited list of round numbers, or control or general variables.

    Shortcut: use a `rounds="*"` to save data from all rounds.

  - `getCurrent="1"`: If specified, get the `current` submitted-data archive from the server. This is created when a `toCurrent="1"` option is used in a submit event. Use of this `current round` can speed up processing (since a smaller file is downloaded), but does require some caution (i.e.; using updateSubmitted appropriately).
    Note: if `getCurrent="1"` is specified, `rounds` is ignored (`rounds="*"` is used).

  - `all`: optional. If all="1" is specified, than save all records, including intermediate records (that is, all [ct] records). Otherwise, only save the final records (for a client/round).
  if : conditional execution of a do action
  Syntax:
  <if value="logical equation"> <action> ... </action> .. <action> ... </action> </if>
  where...
  - the `logical equation` should be an equation of the form:`a1 cond a2`
  - `a1,a2` : equations that may include general and control variables
  - `cont` one of `EQ NE GE LE GT LT`
  If the logical equation evaluates to `TRUE` , then all the <tasks> (between the <if> and </if> are executed. Otherwise, they are skipped.

  #### Notes:

  - You can nest `<IF>.`
    For example:
    <if value="goNextRound.c eq 1 "> <if value="nowround.g ne computedRound.c"> <if value="confirm('Are you sure?)" > <alert where="status"> okay, going to next round </alert> </if> </if> <if value="nowround eq computedRound.c"> <alert where="status"> going to next round ! </alert> </if> </if>
  join : Enable, or disable, new participants joining this session
  Syntax:
  <join allow="n" />
  where
  - `allow="0"` or `allow="N"` : do not allow new participants to join
  - `allow="1"` or `allow="Y"` : do allow new participants to join
  - `allow="R"` : do not allow new participants to join, but do allow current participants to rejoin.
  If `allow` is not specified, an error will occur
  loadScenario: Load parameters specified in a scenario file.
  Syntax: `<loadScenario />`

  `loadScenario` will first display a list of scenario files specified for this session. This will usually include the instrument and session specific defaults. You will then chose which scenario to use. After chosing, the scenario file will be read and `general` parameter will be saved. You can then use `postCAP` to save these to client accessible parameter files.

  Note that you can create a scenario (for this session) by using the Scenarios option at the top of the control panel screen.
  Also, any instrument specific scenarios, that existed before the session was created, will be available.
  Useful trick: NOWROUND_SCENARIO
  Whenever a new scenario is loaded, the `NOWROUND_SCENARIO` GENERAL variable is set to `0`.
  Often, it is useful to increment NOWROUND_SCENARIO whenever a new round starts. Thus, `NOWROUND_SCENARIO` can be used to count the number of rounds this treatment (scenario) has been running.

  For example: when `NOWROUND_SCENARIO` equals `1` (say, after the SPEC file augments `NOWROUND_SCENARIO` when a new round first starts), a set of random values (say, as produced with `dsvyRandom()`) can be replicated. This is a nice way of maintaining the same values across the same relative round in different treatments.

  loadSnapshot: Load session specific parameters that were previously saved using a takeSnapshot.
  Syntax: `<loadSnapshot >`

  takeSnapshot and loadSnapshot are typically used to allow recovery from a browser reload: so that you can retrieve the current (as of the last `loadSnapshot` action) status of the session (rather than reloading the session defaults, which may incorrectly reset current status information for this session.)

  Note: a somewhat more dynamic alternative to `loadSnapshot` is recoverParams.

  monitor: process all `<monitor>`
  The `<monitor>` command in a `<do>` causes all <monitor>s (that appear in a `<form>` or in the `<panel>`) to be immediately processed.
  Syntax:
  <monitor />
  The basic use of `<monitor />` is to force update of variables that have just been changed.

  > Ny default, `<monitor>`s are updated every 5 seconds. So one uses `<monitor />` to keep the display very up to date!

  next_task: specify what the next task should be
  `<next_task>` is used to modify the Next task button at the top of the control panel. This button is used as a navigation aide -- when clicked, it highlights an element. Typically, this should be an element that is used to invoke a form or a `<do>` (that is, an element with a `doTasks` or a `doForm` attribute).
  You can also use the <focus> task to set the focus
  Actually, you can automatically highlight the element (without using the Next task button).

  Syntax:
  <next_task var="aControlVar" value="anId" open="n" strong="1" focus="anID" >a short description</next_task>
  where:
  - `value="anid"` : If specified, the case-sensitive ID of the element to highlight.
  - `var="aControlVar"` : If specified, and if `value` is not specified, a control variable containing the value of the ID. This is not often used
  - `strong="1"`: optional. If specified, a stronger highlighting is used (when the Next task button is hit)
  - `focus="aName`: optional. If specified, focus will be moved to an alement with a `name` attribute of `aName`. If not specified (and `open` is not specified) the focus will be moved to the Next task button. Note that the element recieving focus should be an `<input name="aname" >` or an `<a name="bname" >`.
    Special values of `aname`:
    - `0` : do not change the focus
    - `_top` : scroll to top of page
    - The next several assumes the instrument's control panel is built from the generic dSurvey control panel.
    - `_topBar_` : the utilities bar (top of the page)
    - `_taskHistory_` : the task history bar (near the top of the screen)
    - `_customTasks1_` : the top of the Session tasks table
    - `_customTasks2_` : the 2nd set of custom tasks (below _customTasks1_)
    - `_statusDisplay_`: The status/results area
    - `_formDisplay_` : The form entry area
  - `open="n"` : optional. If specified, n can be `1` or `2` or `3`. Note that when `open` is specified, the Next task button does not need to be clicked -- in fact, it is not even displayed).
    - `1`: then the element is automatically highlighted (and it recieves focus)
    - `2`: then the element is automatically clicked -- the `<do>` it contains is executed.
    - `3`: same as 1, but do not move the focus to this element
  - `a short description`: A short description to use as the mouseover title of the Next task button.
  Notes:
  - `<next_task />` has a special meaning -- it means use the ID specified in the `FIRST_TASK_ID` control variable (and use the description specified in the `FIRST_TASK_DESC` control variable). These variables should be defined in the `<init>` section of the instrument's CONTROL.XML file.

    FIRST_TASK_ID is supposed to be used to point to the first instrument specific task -- the `start2` pre-session task uses it!
    You can also specify `first_task_goto=1` -- instead of a `Next Task` button (that shifts focus to this first task), the first task will automatically recieve focus (and the `Next Task` button will not be displayed).

  - Using `open="2"` to chain forms: It can be convenient to chain forms -- to allow one form to open another form, and when this second forms is submitted, control is returned to the first form. The `open="2"` option can be used to do this.
    Example
    Somewhere in your <panel>, a link that invokes form1 <div doform="form1" id="form1Link">Modify form1 parameters?</div> In form1 (<form name="form1" >) <div doForm="myForm2">First modify form2 parameters?</div> Note when this is clicked, any changes on form1 will be lost. On form2 <submit noClose="1" do="doForm2" summary="Form2 " > Change parameters, return to form1 </submit> Note the use of noClose="1". This is required: if you do not include it, then the form area is closed (so form1 will not be displayed). Also note that a <quit> will not return to form1. In the doForm2 <do> <next_task value="form1Link" open="2" /> This will automatically invoke the doForm="form1" link -- which causes form1 to be displayed in the form area As noted above, any changes you made to form1 (before you clicked the "First modify form2 parameters" link) will be lost. Note that doForm2 really doesn't need to do anything else!

  postVar: Set one, or several, variables on the server
  Syntax:
  <postVar > equation </postVar>
  or
  <postVar name="sname" value="avalue" />
  where
  - `equation:` an equation of the form: `sname=equation`
  - `sname:` name of server variable (to save)
  - `equation:` an equation that can contain numbers, 'quoted strings', parameters, etc (see SET for the details)
    Example:
    sround=nowround (nowround is the nowround control variable) sversion=@sVersion+1 (save value of 1 + the most recently read value of the sVersion "server variable")
  - or ...
  - `name="sname":` name of server variable to save (sname is the name it will have on the server)
  - `value="avalue"` : value to use: used as is (no conversion of variables, etc)
    Example:
    <postVar name="nowVersion" value="3" />
  postCAP: Create client-accessible parameter files on the server.
  postCAP will create client accessible parameter files on the server. These can be read by clients, and are used to specify parameters (say, parameters to use in the next round).

  Syntax:
  <postCAP type="atype" name="aname"> <general> list of variables </general> <message> list of variables </message> <reference> list of variables </reference> <users ids="list of ids"> list of variables </users> </postCAP>
  where...
  - `atype:` either`SESSION, ROUND,` or `OTHER`
  - `SESSION`: save to server a client-accessible XML data file for use as session specific variables
  - `ROUND`: save to server a client-accessible XML data file for use as round specific variables
  - `OTHER` : save to server a client-accessible XML data file containing variables
  - `aname`: optional. Only used if `type="OTHER".` The name of the client-accessible, session specific, XML data file to create on the server. Will overwrite any existing client-accessible file (for this session) of the same name.

  #### Details on types of data (<general>, <message>, <users>, and <reference>)

  <general> | List of GENERAL and resultsData variables to include in the XML data file to be created.

- Often, GENERAL variables will include session-specific variables read using <getParams>
- `resultsData` variable are specified by using `varname.R`

  Shortcuts: | `*` : use all the variables in the `general` database, non-client specific results data, all variables in the `currentParticipants` database, all the `message data`. `*C` : use all variables in the `general` database that have changed since the last `postCap`. This includes any general variable that was never saved to a `postCap` file (thus, on the first save of `postCap` file, `*C` and `*` are equivalent). `*.R` : All the `general` (non-client specific) variables currently specified in the `resultsData` database `*.F` : All the `general` variables modified in a FORM (since the last call to postCAP) `$varname` : Use the variables specified in the varname control variable. For example, the variable created using the `generalVars` option in getParams. Eg: if `avarname` equaled `CARS DOGS CATS`, then using `$avarname` will cause `CARS, DOGS`, and `CATS` o be inserted in the list (of general variables to write).

  Note: if you specify a variable more than once (say, in a shortcut and explicitily), the extra reference will be ignored (thus, specifying a variable once is no different than specifying it a zillion times).
  <message> `message` data is used by dSurvey's message feature. You can write `user`, and `currentParticipant` data to the `<message>` section of a CAP file.

  You can specify two kinds of variables in the variable list:
- `varname.P` variables refer to `currentParticipant` data,
- `varname.U` variables refer to `user` data, Note that you must specify a .P or a .U!

  Shortcuts |

- If *.P or `*` is specified, then the following variables are written...
- `clientIds` (hint: see technical note below on the importance of `clientId`!)
- `NAME`, `NICKNAME`, `CONTACT` (assuming a generic Join-a-session page was used). Depending on how the session is specified, some of these may be just empty strings.
- Other `currentParticpants` data (say, created using a custom Join-the-session page).

- `*.U` is not supported!

  #### message_options

  In addition to variables specifed in a variable list, the value of `message_options` `control` variable is always written to the `<message>` section of CAP files.

  `message_options` are used to control how/when participants display messages. These options can be set using the <message> in a SPEC file. However, it is generally more convenient to use `message_options` provided via a CAP file (it is a convenient wayto make on-the-fly change to the participant's message options).

  When a control panel starts, it will use the `message_options` variable in the `session descriptor file` to initialize a `control` variable with a name of `message_options`. The value of this variable will be included in CAP file whenever a `<message>` section is specified.

  Like any other `control` variable, it is possible to change the value of `message_options`
  Example:
  <do name="foobar1" > < set > message_options.c='show , notify , poll=30 ' </set > </do >
  Alternatively, the Messages generic control panel option has a `Change Options` selection -- you can use that to change the `message_options` control variable.

  Reminder: no matter how the message options are changed, they will not take place immediately. You first have to create a CAP file (that contains a `<message>` section), and then the participants have to download this CAP file (say, when a new section is started).
  Technical notes:
- `clientIds` are used to create participant addresses. If you do not include `clientIds`, participants will not be able to send messages!
  Thus, using `*.P` is recommended!
- Variables are saved using a comma delimited vector of values (one value for each current participant).
- `<message>` data is always retained -- a `<params priors="RESET" >` will not effect them.
  <reference> List of reference variables to include in the XML data file to be created.

  Shortcuts:

- `*` : use all variables in the`referenceData`. If * appears, then ignore everything else!
- `$varname` : See the description under `general`
  <users> For each currently known participant (as determined using the most recently retrieved list of participants) a seperate `<USER> ... </USER>` record will be written to the XML file; with each record containing the contents of the variables specified in varlist.

  #### varlist (in <users>):

  There are several kinds of variables that varlist can refer to:
  1. `userData:` variables either read from a parameters file (using getParams). More typically, variables assigned to a participant from a reference dataset (using assignRefID and resolveReference)
  2. `currentParticipant` : permanent variables, usually assigned when the participant joined. Also, the REFID (as assigned by assignRefID). The permanent variables always includes the NAME, NICKNAME, and CONTACT.
  3. `resultsData:` Current results for this participant.
  To specify these variables, the following syntax is used:
  1. `userData:` : `varname.u` :: Example: `group1` or `group1.u`
  2. `currentParticipants:` `varname.c` :: Example: `refid.c`
  3. `resultsData:` `varname.r` :: Example: `payout1.r`

  #### Shortcuts used in varlist:

  - `*` : use all variables in userData, currentParticipants, and resultsData. If * appears, then ignore everything else!
  - `*.x` : where `x` is `u, c,` or `r` : write all the `userData,` `currentParticipants,` or `resultsData` variables. You can use 1, 2, or 3 of these together.
  - You can also include variables stored in a control variable by using `$varname`
  More details on `postCap` (including information using * as a wildcard, and renaming variables).

  Technical note:
  - `currentParticipants` data specified under <user> can be used to create dynamic web pages (i.e.; they can be used in a `<show var="varname" >`). In contrast, `currentParticipants` data specified under `<message>` are `only` available to dSurvey's message feature.
  recover parameters from snapshot and CAP files
  Syntax:
  <recoverParams " />
  `recoverParams` will retrieve information from the server about the state of the session. Thus, `recoverParams` is meant to be used when a browser refresh occurs.
  `recoverParams` is similar to loadSnapshot -- but it is somewhat more dynamic (since it uses the CAP files also).

  `recoverParams` will do the following:
  1. Read a snapShot file
  2. Read the session-CAP file
  3. Read the round-CAP file
  The notion is to recover the state of all the general, user, and reference parameters -- starting with a snapShot, and then updating this information with the session-specific CAP file, followed by another update using the latest round-CAP file.

  Note that if any of these files (snapShot, session CAP file, or round CAP file) do not exist, an error will occur. So be sure to create a snapshot (not that the dSurvey generic control-panel will automatically create a snap shot after all participants have enrolled).
  resolveReference : add variables from Reference Variables to User Variables
  Syntax:
  <resolveReference refid="aRefID" vars="varlist" />
  where:
  - `aRefID` : the name of a currentParticipants variable, to match against the reference ID. Note that the "reference ID" is the value specified in <row ID="referenceID">of the REFERENCES client-accessible parameters file. Typically, refid="aRefID" is not specified, in which case use the REFID variable (i.e.; the REFID variable created by <assignRefid>.)
  - `vars` : list of REFERENCE variables to add (space delimited).
    Or: use `vars="*"`, or `vars=" "`, to add all variables.
    Or: don't specify a vars attribute (to add all variables).

    Note that if a variable appears in varlist that is not a `REFERENCE` variable, it will be ignored.

  The basic idea is that the `reference` data provides user specific values. In particular, the aRefId variable is used to lookup which data row (in the reference variables database) to use. Note that it is completely legal for more than one client to have the same value of the reference ID (in which case they will be assigned the same values from the reference variables database).

  Note that `resolveReference` is desgined to be called AFTER getParams, getParticipants, and assignRefID.

  reset: reset the GENERAL, USERS, SERVER, CONTROL, and/or REFERENCE variables
  This will reset (delete) the `GENERAL, USERS, SERVER, CONTROL,` and/or `REFERENCE` control panel databases.
  If you do not specify anything between the `<reset>` and `</reset>`m then all 5 are reset. Otherwise, include any subset of these five.

  Thus: `<reset> USERS REFERENCE</reset>` means reset the USERS and REFERENCE databases, but do not reset the CONTROL and SERVER and GENERAL databases

  Note: when a control panel is first loaded, all variables are reset.
  show: replace with current value of a variable
  Syntax:
  <show name="varname" />
  where
  - `varname:` a server, general or control variable. By default, variables are assumed to be control variables.
  - `<show .. />` can be used ...
    - inside of `<alert >`
    - inside of `<form>`
    Each time the <alert > is processed, or each time a <form> is invoked, the `<show>` will be changed (to reflect the current value of `varname`).
  Example: `<show name="nowround.g" />`

  Note: in a `<form>`, you can also use <set> to set and/or display variables.
  readLocal: retrieve, from the local hard drive, an XML data file.
  For example: read, from a local file, the results of processing a round of submitted data using external software.
  Local data files retrieved with `readLocal` will be stored in the control panels `workData` control-panel database. `resultsData` can be extracted from `workData`, which can be saved to the the participant's `user` data (see Saving results for details).

  Note that file retrieval requires you to fill in a form in the FORM area of the default control panel (specifically, in an element with `id="_formArea"`) using a standard `<input type="file" ..> file` selection box.

  Syntax:
  <readLocal file="submit1.xml" />
  where:
  - `file`: optional. A suggested file name (to retrieve)
  Example:
  <radio do="getResults" value="2" >Click here to retrieve results </radio> </p> and <do name="getResults" > contains: <readLocal file="newResults.xml" />

  #### Advanced options

  You can also use the uploaded data (that is stored in the `workData` internal database) to create the `resultsData` internal database.
  - `makeResults="1"` : if specified, the resultsData database will be populated using data read from the XML file By default: the most recent (that is: the largest valued) round (of the possibly several rounds) specified in the xml file will be used to create resultsData.

    If you specify `makeResults`, you can also specify the following:
  - `checkRound="varname"` : If specified, varname should be a control or general variable. Its value will be compared to the most recent round specified in the XML file, and a javascript confirm will be displayed if they are not equal.
  - `useRound="rnum"` : If specified, create resultsData using data (in the XML file) from the `rnum` round rather than from the most recent round specified in the XML file). `rnum` can be an integer, or a general or control variable. Be careful using `useRound` with `checkRound`!
  - `roundRead="dvar"` : optional. `dvar` should be a dSurvey variable name (either control or general). The actual round used (to create results data) will be saved to this `dvar` variable (i.e.; the maximum round, or the round specified in `useRound`. If a problem (no data available), dvar will be set to ''.
  saveData: write a control panel database to a local file (using an XML like format)
  Syntax:
  <saveData type="atype" filename=aname.xml" gexpand="0/1/2" submitRound="sround" submitSkip="0/1" name="descriptive_word" round="useround" showType="1" > varlist </saveData>
  Note: with a few exceptions, the syntax of `saveData` is identical to the syntax of uploadData.
  where:
  - `atype:` `GENERAL, USERS, PARTICIPANTS, RESULTS,` , `CUSTOM`, or `HISTORY`.
    HISTORY, is designed to be used with <uploadData>. It is rarely used with <saveData>.
  - `filename:` optional. Suggested filename.
  - `round:` optional. The round number to use (when writing records).
    You can use a variable name (general or control), or you can use a number. If not specified, the nowRound general variable is used.
    Note: `round` is used to identify what the current round is. This current round information will be saved (along with the variable values). Thus, each time `saveData` (or `uploadData`) is invoked, the saved values will be identified by the value of this `round` variable.

    Note that for `submittedData`, see the description of `submitRound` below.
  - The next option is only used with `CUSTOM` and `HISTORY`.
  - `gExpand` : optional. Controls whether arrays in `general` data are expanded.
    - `gExpand="0"`: do not expand arrays.
    - `gExpand="1"`: expand arrays, using `arrayName[ith]` syntax
    - `gExpand="2"`: expand arrays, using `arrayName[ith]` syntax, but do not write `undefined` array values
    By default (i.e.; if `gExpand` is not specified): `gExpand="2"` is used.

    Example: assume an array `DVALUES` has values: `DVALUES[1]=1.0 DVALUES[2]=0.9 DVALUES[3]=1.5` and `DVALUES[0] is undefined`.
    then, the following will be written to a the CUSTOM (or HISTORY) archive.
    - `gExpand="0"`: `<DVALUES>,1.0, 0.9, 1.5</DVALUES>`
    - `gExpand="1"`: `<DVALUES_0_>undefined</DVALUES_0_>` `<DVALUES_1_>1.0</DVALUES_1_>` `<DVALUES_2_> 0.9 </DVALUES_2_>` `<DVALUES_3_> 1.5 </DVALUES_3_>`
    - `gExpand="2"`: `<DVALUES_1_>1.0</DVALUES_1_>` `<DVALUES_2_> 0.9 </DVALUES_2_>` `<DVALUES_3_> 1.5 </DVALUES_3_>`
  - The next several options are only used with `CUSTOM`.
  - `name` : optional. Should be a name for the `custom` database being built. This name is used by the server when storing data. It is also used by downloadData when retrieving data. If `name` is not specified, `stuff` is used.
  - `showtype` : optional. Used with `CUSTOM`. If `showtype="1"`, then a few attributes are added to elements in the XML file. These are a `type` attribute, and (if `submitRound="L"` is specified), a `round` attribute.

    Values of `type` |

  - `type="G"` : General data
  - `type="S"` : Submitted data
  - `type="R"` : Results data
  - `type="P"` : Participant data
  - `type="U"` : User data
    `round` The `round` attribute is only added for `submittedData` variables, and only if `submitRound="L"`. It will equal the round used for this variable's value (for this participant).
    Example:
    <gvar1 type="G" >5 </gvar1> <svar1 type="S" round="5">31.5 </svar1> <svar2 type="S" round="6">151 </svar2>
    If `showtype="0"` (the default), this information is not recorded. Note that if you use Excel to convert an XML file to an XLS file, these `type` attributes will be saved in their own columns. This can be annoying (hence the default is to not create this attribute).

  - `submitRound`: Used with `submittedData`: this should be a number, or a variable, that identifies which round to extract data from. If it is not specified, the value of the `round` is used.

    Note that `submittedData` typically contains multiple rounds of data. Since `saveData` (and `uploadData`) save only one round of data (albeit for all participants), one must identify which round (from `submittedData`) to use. Hence the differentiation between `round` and `submitRound`!
    Special value: if `submitRound="L"`, then the most recent round containing this variable is used. This can vary across variables, and even across participants. Basically, starting with the round defined by `round`, dSurvey will look backwards until it finds a round (in `submittedData`, for this particpant) that contains the specified variable. Note that this may differ across variables; so that some variables may be from round T, while others may be from round T-1.
  - `submitSkip`: Only used if `submitRound="L"`. If `submitSkip="1"`, then look for a non-blank value of the variable. Thus, it is not enough that a round contains a variable, the variable's value must also be non-blank.

    The basic idea: `submitRound="L"` (perhaps with `submitSkip="1"`) allows you to summarize several rounds of data -- say, where each submitted round contains a different set of variables. After all these rounds have beenc completed one could use a `saveData` (or `uploadData`), with these options that specifies these multitude of variables. This may be easier than using a `saveData` (or `uploadData`) at the end of each round.

  - `varlist`: list of variables to save. If not specified, save them all (except for `CUSTOM` and `HISTORY`).
  This write the current round's `atype` control-panel database to a file on the local hard drive.
  To upload data to the server, use <uploadData>.

  Note:the syntax of `<saveData>` and `<uploadData>` are nearly identical.
  - For `GENERAL,` one record is written, containing the values of the general variables.
  - For `PARTICIPANTS,` a seperate record for each of the current participants (as contained in the `currentParticipants` control panel database) is written.
    Note: `currentParticipants` variables include `NAME`, and (if specified by the instrument descriptor file) `NICKNAME` and `CONTACT`.
  - For `USERS` and `RESULTS,` a seperate record for each current participant is written.
  - For `HISTORY` and `CUSTOM,` a seperate record for each current participant is written.
  In all cases, each record written to a file (for `saveData`), or stored to the server (for `uploadData`), will contain the round-number.

  If `varlist` is specified, then only the variables specified in varlist will be written/saved.
- For GENERAL, PARTICIPANTS, USERS, and RESULTS: variables specified in `varlist` must refer to the appropriate database. For example:, you can not specify a PARTICIPANTS variable if `atype="GENERAL"`.
- For CUSTOM and HISTORY, you should specify variables from either the GENERAL, USERS, SUBMITTED, RESULTS, or PARTICIPANTS databases. Note that if you do not specify a type (using a `.type` syntax), then GENERAL is used.

  #### Notes:

  - results data: the current values for the * id (for current round, and for the * round), is also written
  - `results`, `user`, and `participants` data: if a "array like name" is used (say, FOO[1]), then a "_index_" is added to the "array name". For example, FOO[1] is saved as`FOO_1_`
    Note that saving "`FOO`" will not cause `FOO_0_ ... FOO_N_` to be saved.

    Similarly, in `custom` and `history`, assuming `gexpand="0"` is not specified, general variables that are arrays will be expanded using the same syntax.
  - `submitted` data: If atype is HISTORY or CUSTOM, you can include data submitted by participants (which you must first download with getSubmitted first).
  Using * in varlist
  For the `USERS`, `PARTICIPANTS`, `SUBMITTED`, and `RESULTS` databases, you can use * as a wildcard. That is, in varlist you can include words that contain an *: and all variables that match this wildcarded word will be included in the output.

  For example (abstracting for the moment from which database is being queried).....

  If `price1,price2, cost[1]` and `cost[2]` variables exist, then:
    `income cost[*]`
  is equivalent to
    `income cost[1] cost[2]`
  Similarly, if `price1` and `price2` are specified
    `income price*`
  is equivalent to
    `income price1 price2`
  Please note that this is not supported for `GENERAL` (since `GENERAL` has built in support for arrays, and the major use of * is to specify all elements in an array). It is also not supported for `HISTORY` and `CUSTOM`.

  #### Using varlist for history, and custom, data:

  As noted above, `HISTORY` and `CUSTOM` are somewhat different: you can specify general, participant, users, submitted data, or results variables. But you must specify something: the * syntax (or nothing specified syntax) is not supported.
  - To specify a `generalData` variable: `varname.g.` The value for this variable will be saved in each record (thus, the value will be the same in each record)
  - To specify a currentParticipants variable: `varname.c.`
  - To specify a `usersData` variable: `varname.u.`
  - To specify a `submittedData` variable: `varname.s.`
    The round of `submittedData` that will be used is specified by the `round` attribute (of `<saveData>`).
    If, for a particular client, no information exists for this round, empty values ('') are used.
    Reminder: to include `submittedData`, you must first use getSubmitted to retrieve this client-specific submitted data.
  - To specify a `resultsData` variable: `varname.r.` If necessary, the * id version of this variable will be used (thus, like `generalData` variables, it is possible for the same value to be used in all records)

  #### Note on CUSTOM and HISTORY

  `HISTORY` is designed to be used with `uploadData`, it is rarely used with `saveData`.
  `HISTORY` and `CUSTOM` do essentially the same thing: they allow you to to build a custom dataset, one containing a mixture of variables from the `Gneral`, `Users`, `Participants`, `Submitted`, and `Results` control-panel databases.

  They are typically used for somewhat different purposes:
  - `CUSTOM`: often used with `uploadData` to build a final product dataset:something that (when the session is over) can be downloaded (with downloadData) and used for data analysis.
  - `HISTORY`: the history archive is designed to work with the `recoverPrior` event action (in your SPEC file) -- which will rebuild a history page after a browser refresh.

  The only technical difference between `HISTORY` and `CUSTOM` is where the data is saved.
  - `HISTORY`: a special `history` archive is created -- which (by design) can be used when displaying a history of a client's decisions.
  - `CUSTOM`: you must specify a name. Note that you can even build multiple custom databases by specifying different names.

  In other words,
  - `HISTORY` and the the other archive datasets are session specific: appending to them always appends to the same "session specific" database.
  - `CUSTOM` archive datasets are boh session specific and named: so appending to a session specific custom database requires using the same name attribute.

  #### More notes on HISTORY

  `HISTORY` is designed to support a history of every client. This can be handy if a client has to reload his browser (say, his browser gets hung).
  When a browser hang happens, all the client's prior results (that are stored in the browsers's memory) get wiped out: which means that any review your history options won't work.

  1. variables are saved in the `HISTORY` database (on the server),
  2. and if a browser reload occurs, the client reads (and extracts client specific data from) this database,
  3. and uses this client-specific data to rebuild the prior results (that were wiped out of the browser's memory)
  4. then a review your history will work properly
  See recoverPrior for the details on how to rebuild a history after a browser refresh.
  set: create a GENERAL or CONTROL variable.
  This will create a general variable, and assign a value. If the variable exists, the old value will be overwritten.
  Syntax:
  <set show="doshow"> varname= equation </set>
  where:
  - `varname:` a general variable, or a control variable. Note that varname can not refer to a server variable!
    By default, control variables are set. To set a general variable, append a `.GENERAL` (or a `.G`). You can also set `USER` variables by appending a `.U` to the variable name.
  - `equation:` A math equation, or a number, or a 'quoted string'. Varname will be set equal to the value of equation.
    Equation can contain numbers, general variables, control variables, server variables, math operators, functions, and 'quoted strings'.
    By default, unspecified (with no prefix or suffix) variables are assumed to be control variables.
  - `show="doshow"` : optional. If `show="1",` display the new value of varname in the status area.
    If `show="2"`, show the value and save it to the history-of-actions.
  Examples:
  nowrnd=1 %newr=nowrnd+1 cost=cost.G * @NowMult/100 ; yourProfit.U=profit1.r + profit2.R

  #### Using `set` to call custom javascript procedures.

  `set` can be used to call your own custom functions. This is especially useful when you use your own javascript function to compute results.

  For example, the following calls the computeWinners function (say, a function that computes winners) stores the results returned by computeWinners in `ares`, and also display these results in the "status" area (without saving it to the action history):

  <set show="1"> ares=computeWinners() </set>
  stop: stop processing this DO.
  Typically used inside of an `<IF>.`
  Example:
  <if value="totEarn gt 100" /> <stop /> </if>
  takeSnapshot: Save a snapshot of current control panel databases
  Syntax:
  <takeSnapshot />

  Save all the current parameters (`GENERAL, USER, CURRENTPARTICIPANTS`, and `REFERENCE)`, for this session, to the server. This snapshot can be reloaded (say, if you need to reload the control panel) by using loadSnapshot

  Technical note: takeSnapshot will also save any current results as <users > data (in the snapshot file).
  updateSubmitted: Move the `current` submitted data (on the server) to the `all rounds` submitted data (on the server)
  Syntax:
  <updateSubmitted />

  This will move the contents of the current round submitted-data-archive (on the server), to the `all rounds` submitted-data-archive (also on the server).

  Note that move means:

- all entries in the `current round` submitted-data-archive will be copied to the end of the `submitted-data-archive`
- The `current-round` submitted-data-archive will be cleared of all entries Thus, `updateSubmitted` should be used at the end of a round; so as to save the submitted data in a permanent location, and get ready to start accepting submissions for the next round.

  Note that the use of `current round` submitted-data is an efficiency trick; it leads to smaller files being processed by the server and control-panel. However, if rounds & clients are not that numerous, it is simpler to save data directly to the `all rounds` submitted-data-archive (and not bother with this intermediate step).

  updateDiv: Replace the contents of an element on the control-panel screen
  Syntax:
  <updateDiv type="howdo" append="1" where="idToUpdate" addStyle="styleString" > stuff to update </updateDiv>

  where:

  - `where="idToUpdate"`: The id of an element (typically a `<divd>`) whose contents will be changed. This element is typically in the `<panel>` section, but it can be other places; such as in a currently displayed `<form>`.
    If no such `idToUpdate` exists, an error message will be displayed.
  - `append="1"`: Optional. If specified, the contents of the element will be appended to. Otherwise, the contents will be replaced
  - `type="howdo"` If `type` is not specified, `type="block` is used. In other words, by default `updateDiv` will make visible a hidden element.
  - `howdo="NONE"`: make invisible.
  - `howdo="BLOCK"`: make visible (as a block element).
  - `howdo="INLINE"`: make visible (as an inline element).
  - `howdo="TOGGLE"`: toggle. This is the default (if `howdo` is not specified)
  - `addStyle="styleString"`: if specified, `styleString` should contain valid CSS style specifications. They will be added to the style of the `where` element. Note that if you just want to change a style, you can use `append="1"`, with `stuff to update` empty.
  - `replaceStyle="styleString"`: Similar to `addStyle`, but replace the current style (rather that add to it). If both `addStyle` and `replaceStyle` are specified, `addStyle` is ignored.
    Bonus: `replaceStyle` recognizes three special styles
  - blueLink (ready to click)
  - greenLink (task in progress)
  - purpleLink (task complete) These styles match the link colors and format used by the clickStyle special attribute (used in the `<PANEL>`.

    These special styles are an alternative to using clickStyle; it allows you to change styles at your discretion (rather than during or after a tasks).
    For example: if you want to change a link's coloring from purpleLink to blueLink after a second link is pressed!
  - `stuff to update`: The text contents to use
  Note that <show> can be included in `stuff to update`. Thus, `<updateDiv>` can be used to dynamically update the control panels tasks tables.
  However, no other HTML can be included in `stuff to update`.

  For example:
  <udpateDiv where="showCurrentRound"> ( <show var="nowround.g /> ) <updateDiv> ... The current round is <span id="showCurrentRound" /> !

  Notes: |

- To just change the visiblity of an element, and not change its contents or style, you can use <display>
- To just change the style, without changing the contents, use `append="1"` and leave the `stuff to update` empty.
  For example: `<updateDiv ... append="1" ..> </updateDiv>`
  uploadData: post current data to an archive on the server (using an XML like format)
  Syntax:
  <uploadData type="atype" name="desc_word" round="around" showType="1" > varlist </uploadData>
  where:
  - `atype:` `GENERAL, USERS, PARTICIPANTS, RESULTS,` or `HISTORY.` Or `CUSTOM.`
  - `round:` optional. The round number to use (when writing records).
  - `name` : optional. Used with `CUSTOM.` Should be a name for the `custom` database being built.
  - `showtype` : optional. Used with `CUSTOM`. If `showtype="1"`, then each value (saved in an XML database) will have a `type` attribute that denotes the source of the data
  - `varlist`: list of variables to save. If not specified, save them all (except for `HISTORY`).
  Notes:
  - The syntax for `uploadData` is similar to <saveData> -- so see <saveData> for the details.

    What is the difference between `uploadData` and `saveData`? |

  - `uploadData` will append the contents of a control panel database to a special archive located on the server. Thus, current values of the database are added to existing values (say, to values `uploaded` earlier in the session.
  - `saveData` will write the contents of a control panel database to a file on the computer (that is running the control panel). This is an overwrite -- only the current values of the database are saved.

  - Data from a server-side archive can be retrieved using downloadData.
  - Hint: Use `uploadData` to build a dataset (saved as `custom`) that contains all the variables you might want to use in further analysis. And then (at the end of the session) use `downloadData` to retrieve it.
  - Hint: Use `uploadData` to build a dataset (saved as `history`) that contains variables that can be used to <recover> a particpant's history.
  <FORM>
  FORM is used to specify a "form" that can recieve user input. In particular, user input that specifies values of general parameters, and control variables.

  FORM can contain standard HTML display elements (such as <b>, <p >, and <h3>). It can also contain input fields: which can be:

- standard HTML FORM elements (such as <input>, <select>, and <textarea>), or ...
- special tagnames used to create fancy input fields: These include <RADIO>, <ARRAY>, <NUMBER>, and <STEP>.
  Within FORM, attributes of these input fields are used to specify what general, or control, variable to set. Clicking, checking, selecting, or changing text (as appropriate) will change the desired general, or control variable.

  Note that variables are modified ONLY if

  - an input-field is acted on (clicked, checked, etc.),
  - and either
  - a `submit` input field is clicked,
  - or a `step` or a `radio` input field contains a `do` attribute

  When one of the above happens,

- changes will be saved to general and control parameters.
- and, the tasks specified (via a `do` attribute in a `submit`, `radio`, or `step`) can update parameter files on the server (say, by using `postCAP`).
  Syntax:
  <form name="formName" height="aheight" vuTasksTable="NO/YES/TOGGLE"> xhtml code <div doForm="xx" doTasks="xx" doDisplay="xx" doCheck="xx" doValue="xx"> a message </div> <set show="1"> avar=aequation </sett> <if value="1" > .... </if > <monitor var="avaf" if="ifEquation" > . ... </monitor > <tagname name="varname" value="avalue" displayIf="logical equation" /> <submit do="doname"> a message</submit> <quit > quit message </quit> xhtml code </form>
  where the `<form>` attributes are:
  - formName
    The name of this form: it is matched to the value of a doForm attribute specified in an element in a control panel's <panel> section.
  - height
    Optional: it is the height of the form area used to display the form (on the control panel's screen). If not specified, 70% is used.
  - vuTasksTable
    Optional: `vuTasksTable="NO/YES/TOGGLE"` controls whether the tasks table is hidden:
  - `NO` (or `0`): task table will be hidden
  - `YES` (or `1`): task table will be displayed
  - `TOGGLE` (or `2`) (or `vuTasksTable=""`): task table will be toggled (ie; if currently displayed, it will be hidden). This is a convenient means of freeing up screen real estate, which can be useful if you are specifying a long form.
    This assume you are using a generic control panel, that uses a `<div>` with an id of `_optionsTables`, to contain the tasks table.

    Note that `vuTasksTable` is usually paired with a `vuTasksTable` in a <quit> or in a <submit >.
  <Submit> and <quit>
  - <submit do="doName" noClose="1" vuTasksTable="NO/YES/TOGGLE" summary="Short message " > a message </submit>
    `Submit` will create a button, with `a message` as the message.
    When clicked, the changes to variables will be made, a `<do>` with a name of `doname` will be executed, and the form area will be hidden (this can be suppressed by using `noclose`).
  - `do="doName"`: Not required, but often used. `doName` is the name of a `<do>` task to run when the `submit` button is hit.
  - `noClose="1"` : the form area will not be closed (it will not be hidden) when the submit button is hit.
    The `noClose="1"` attribute is especially useful when you include (within the form) a `doForm` element -- so that the administrator can invoke a 2nd form from within this parent form.
    In such a case, after submitting this 2nd form you might want to return to this parent form (by judicious use of `<next_task>`).
    In such a case ...
    if the 2nd form's `<submit>` does not contain a `noClose="1"`, then the form area will be hidden (you won't be able to see the reinvocation of the parent form).
    Yeah, this is a silly bug/feature, but for now the work around is to include a `noClose="1"` in this second form.
  - `vuTasksTable="NO/YES/TOGGLE"`: view the tasks table. This has the same syntax as above.
    The idea is to specify `vuTasksTable="no"` in the `<form>`, and specify `vuTasksTable="yes"` in the `<submit>` inside of the `<form>`.
  - `summary="short message"`: Optional. If specified, when this submit button it hit, `short message` is written to the task history bar bar.

  - <quit vuTasksTable="NO/YES/TOGGLE" > a message </quit>
    `<quit>` will be replaced with a button that, when clicked, will close form without submitting (or committing) any variables. In addition, the form area will be hidden.
  - `a message`:The text of the button.
    If`<quit />`; is specified, the button will be:
  - `vuTasksTable="NO/YES/TOGGLE"`: view the tasks table. This has the same syntax as above.
    The idea is to specify `vuTasksTable="no"` in the `<form>`, and specify `vuTasksTable="yes"` in the `<quit>` inside of the `<form>`.
  <div> with doDisplay, doForm, doValue, doCheck, and doTasks attributes
  Within a `<form>`, `<div>` (or `<span>`) elements that have the attributes:
  `doDisplay`, `doForm`, `doTasks`, `doCheck`, and `doValue`
  will be interpreted just like their counterparts within `<panel>`.

  They are supported within `<form>` as a tool for making more complex forms (say, that have a loose heirarchical structure). Please see noClose, or <next_task>, for details on opening forms within forms!

  #### Notes on doForm, etc. within a <form>

  - If a link generated by a `doForm` or a `doTasks` is hit, then the `<form>` is closed (kind of like what happens when a `<quit>` is hit). In particular, values modified within this `<form>` will not be saved.
  - While `doCheck` and `doValue` do something similar to the special tagnames discussed below (such as `<radio>` and `<number>`), they are much simpler.
    In particular:
  - No fancy features!
  - No attempt is made to set their values to a currently existing variable with the same `name`.
  - Only control variables can be set
  <if> and <set>
  `<if> and` `<set>` are processed everytime a form is invoked.
  - `if` is used to include or exclude elements, based on the currrent values of control and general variables.
  - `set` is used to set a control or general variable, or to display the current value of a control or general variable.

  <if value="logical equation"> ... stuff ... </if> If `logical equation` is true, then the `... stuff ...` will be included. Notes:

- The syntax for `<if>` is similar to how if is used in <do>.
- `logical equation` can use control (`.c`) and general (`.g`) variables
- `... stuff ...` can include any elements, including `<if>` and `<set>`.
  <set show="1" > avar=aequation </set>
  or
  <set > aequation </set>
  Where ...
  - `avar` is the name of a control (`avar.c`) or general (`avar.g`) variable (by default, control variable is assumed).
  - `aequation` will be evaluated, and used to set the value of `avar`.
  - `show="1"` is optional. If specified, the value (of `aequation`) will be displayed (the `<set show="1">...</set>` will be replaced by the value of `aequation`)
  - if only `aequation` is specified, then the value (of `aequation`) will be displayed, but no variable will be set. However, if `show="0"`, nothing is displayed.
  Examples...
  <set> revenue1= priceNow - cost1 </set> <set show="1"> volume=myWidth * myHeight </set> <set> alert('This is an alert!') </set> Alternate syntax: <set value="volume=myWidth * myHeight" />
  <monitor>
  You can include zero, one, or many `<monitor>`. They will be processed everytime a form is invoked.

  While the form is active, all contents (between `<monitor>` and `</monitor>`) will be repetitively processed. That is: they will be processed when the form is first loaded, when a `submit` occurs, and every 5 seconds.

  This makes it trivial to dynamically update the form's display!

  Example: | <monitor > The current step = <show var="myStep> </monitor >
  | Whenever the `myStep` variable is changed, this message will be updated. And `myStep` could be a variable that is repetitively updated by the form (without the form being closed).

  Shortcuts | You can use `var` and `if` attributes inside of the `<monitor>` element. `var="varname"` : update the value of the `varname` variable. Note that if the `.type` is not specified, `.control` is assumed. If `var="varname"` is specified, any contents of a `<monitor>` will be ignored! Example:`The current step = <monitor var="myStep />` `if="ifEquation"`: if the `ifEquation` evaluates to `true`, then the contents are displayed (or the `var="varname"`) is displayed. Otherwise, nothing is displayed. Example:`<monitor if="myStep gt 10" > Your step is getting large! </monitor>`

  Notes | <updateDiv> is an alternative to `<monitor>` You can also use `<monitor>` in the <panel>. You can include display attributes (suc as `title`, `style` and `class`) inside of the `<monitor>` element You can include `<if>` (along with `<show>`) in the contents of a `<monitor>` By default, `<monitor>` are updated every 5 seconds. You can force update by using a <monitor /> in a `<do>`.

  Special tagnames used in <form> for data input
  A variety of special `<tagname>` can be used for user input:
  INPUT, OPTION, TEXTAREA, RADIO, ARRAY, NUMBER, and STEP

  The basic syntax is:
  <tagname name="varname" value="avalue" displayIf="logical equation" summary="a message" otherAttributes... />
  Note that the `otherAttrributes` depend on the special tagname.

  You can add attributes to these special `<tagname>` directly, or by using the control panel <attributes> section.
  Of particular interest is the `<change>` attribute: which allows you to specify actions to take if an input field is changed. <change> can ONLY be added by attributes; : you can not specify it within the <tagname>

  The basic attributes (used with all special tagnames):
  - name the variable to change. Varname can refer to a general or control variable. The following case-insensitive syntax is used to indicate which type:
  - aname or aname.general the "aname" general variable
  - #aname or aname.control : the "aname" control variable Note: in contrast to SET, the "default" variable is GENERAL (rather than CONTROL).
  - value: the value to set the variable to when the element is clicked.
  - summary : a message written to the task history bar bar when this element is selected (or otherwise modified).
    Note: you can specify variable values in this message by including words with a syntax of `%varname`, where a space must precede the `%varname`, and `%varname` by default is a control variable.
  - displayIf : optional. If specified, the "logical equation" is analyzed, and if it evaluates to 0 the element is not displayed. Note that all other processing of this element occurs, only the display is effected. As with other "if" statements in control panels, the logical equation can contain control and general variables.
  Notes:
  - the default value of most of the tagnames depends on the current value of the "name" variable. For example: the current value is used to determine whether a checkbox is checked, which radio button (if any) is on, and the default value contained in a text input box.
  - Reminder: values are recorded (for future processing) only if they change.

  #### Details on the special tagnames...

  - <input >
    <input> is not that special -- it is used similar to the way `<input>` is used used in standard HTML forms. It's behaviour depends on the `type`

  - type="checkbox" : the value attribute is used when checked. The box will be checked by default if the current value of the variable matches the "value" attribute A "notvalue" attribute can be used: it is the value that is used when the box is unchecked (typically, if the box is checked by default)
  - type="button" : If there is no value attribute, the current value of the variable is used. A "set" attribute can be used instead of a value attribute. In this case, the "value" attribute is the text in the button, but pushing the buttton yields a value of the set attribute.
  - type="radio" : The default selected radio button depends on the value
  - type="text" : The value attribute is ignored: the default value is the variables current value Notes:
  - `<radio>` offers a more powerful alternative to`<input type="radio">`
  - `<step>` offers a more powerful alternative to `<input type="button">`
  - `<number>` offers a more powerful alternative (for entering numeric values) to `<input type="text">`
    Examples:
    <input type="checkbox" name="NACCEPT" value="6" notValue="1" /> <input type="text" name="faveCar" /> <input type="radio" name="kids" value="0" /> <input type="radio" name="kids" value="1" /> <input type="radio" name="kids" value="2" /> <input type="submit" name="wantBuy" value="1" />

  - <textarea >
    `<textarea>` is similaer to `<textarea>` in standard HTML forms. You should specify rows and cols attributes.
    Example...
    `<textarea rows="3" cols="80" name="currentMessage.g"> </textarea>`
    would be used to modify the `currentMessage` general variable.
    Note that the current value of `currentMessage.g` will be displayed in a 3 row 80 column text input box.

  - <option >
    `<option>` is similar to `<option>` in standard HTML forms. As with regular HTML, each `<option>` should be used inside of a `<select>.`
    Notes:
    - Each `<option>` must contain a `name` and a `value` attribute.
    - Example...
      <select > <option name="myCar" value="civic">Honda </option> <option name="myCar" value="focus">Ford </option> <option name="myCar" value="nova">Chevy </option> </select >
    - When an option is selected, the value (specified in the `value` attribute) will be assigned to the variable name (specified in the `name` attribute).
    - The `<select>` may contain size and style attributes.
    - within a `<select>,` each `<option>` can refer to a different name! So you can change different variables within a single selection box.

  - <array >
    `<array>` is used to create a one row table of text-input boxes; with one table-column per element of an array. This is meant to be used with general parameters that are arrays. The value attribute is ignored (current values of the array are used by default)

    Attributes used in `<array>`

  - nlength="n" : number of elements in this array. A one-row table with `n` cells is created, one cell per element of the array If `nlength` is not specified, and the named variable is a general array, then the number of elements in this array will be used as the length. Which means new values can not be added!
    Note: javascript convention is used: `nlength=N` means last index is N-1 (since first index is 0)
    Technical Note: `length="n"` is a synonym for `nlength="n"`. However, for unknown reasons `length="n"` causes problems with Internet Explorer 8. Therefore, it probably is safest (though a bit less intuitive) to use `nlength` rather than `length`.
  - start="n" : optional. The offset to start at. Thus, `start="1"` means show array elements starting from [1].
    If not specified, all array elements (starting from [0]) will be displayed.
  - size="nchar" : the size, in characters, of each column in the table

  - <radio >
    `<Radio>` is kind of like`<input type="radio" ..>.`
    All `<radio>` elements (in this form), that have the same name, will be grouped together. Only one of them can be checked. So, just like an `INPUT` radio button, when you select one of them the currently selected `<RADIO>` element will be unselected.
    Note that the "value" attribute is what is used as the new value of the variable, while stuff between `<radio ..>` and `</radio>` is displayed.

    #### Other attributes used in <radio>

    - styleNo="a style" display style if this `RADIO` element is not selected. Optional: if not specified, a default is used
    - styleYes="a style" display style if this `RADIO` element IS selected. Optional: if not specified, a default is used
    - styleClick="a style" display style if this `RADIO` element IS selected and a `clickMessage` is specified. Optional: if not specified, a default is used
    - do="formName" optional. If <radio> contains a do="formname" attribute, then clicking on the button is like clicking on a submit: the value of this radio button is set, and then the formname <do> is invoked.
    - nextRadio="1" if `nextRadio="1"` is used, then value is ignored. Instead, when this is clicked, the "next" RADIO element is "clicked" (where next is in order of appearance). That is, clicking a `RADIO` with a `nextRadio="1"` attribute will sequentially execute all the `RADIO` (with this name). When all the RADIOs have been executed, hitting a `nextRadio="1"` `RADIO` resets to the beginning: so that hitting it again will execute the first `RADIO` (again, with this name). Note that for these `RADIO` (with `nextRadio="1"`), style is always used (styleNo and styleYes is ignored). Also, "do" attribute is ignored (the "`do"` of the "next `radio`" will be used).
    - clickMessage="a message" When this radio button is clicked, the displayed message will be changed to the `a message` (using the styleClick style).
    - close="1" Close the form (hide the form area) after clicking this button. Note that a `do` is executed before the form is closed.

    Note that the form area is not hidden when a radio button is used to submit (that is, when a `RADIO` has a `do` attribute).

  - <number >
    <number> is used to specify a text input field with up and down arrows next to it, and/or a scroll bar beneath it. The input field can be typed into, or the scroll bar can be scrolled, or the arrows can be clicked: to increment or decrement the value in the text field. Both typing, and arrowing, can be used interchangeably.

    #### Optional attributes used in <number> :

    - title ="a title" : message displayed on mouseover (of the input box)
    - size="n" : width of input field in characters. Default is 5
    - style="css style" : a css style string used to display the input text box.
    - minimium="amin" : minimum value allowed. An entered or arrow number lower than this will be changed to amin. Can be a numeric value, or a control or general variable.
    - maximum="amax" : maximum value allowed. An entered or arrow number greater than this will be changed to amax. Can be a numeric value, or a control or general variable.
    - inc="ainc" : value increases/decreases by this much when arrow hit. Default is 1
    - default="adef" : if value of variable is '', then hitting arrow casues adef to be used. Can be a numeric value, or a control or general variable. Special case: if `default=""`, or if default is not specified, then a '' is allowed (and a ' ' is used if a non-number is entered).
    - default="adef" : if value of variable is '', then hitting arrow casues adef to be used. Adef
    - arrowName="bname" : bname is "basename" of "arrow" to use.
      If `arrowName` is not specified, than a default of `arrow` is used.
      If specified, `bname` should point to a set of icons in the /dsurvey/docs/icons directory. Currently supported values of `arrowName` are: "Arrow", "ArrowGreen", "Chevron", "ChevronGreen", and "FairytaleBlue".
      If `arrowName="0"` is specified, than arrows will not be displayed.
    - scrollWhere="divid" : divid is the id of a `<div>` (or a `<span>`). If `scrollWhere` is specified, a scroll bar will be written to this `div` (or `span`).

      Optional: you can specify the left and right color using attributes:

    - `lowColor="#rrggbb"`
    - `highColor="#rrggbb"` where `rrggbb` are hex color codes. For example,
      - ababab
      - aa00ee
      - fe8931

    - You can specify `fmt="n"`: this sets how many digits to the right of the decimal place are displayed.

    #### On scroll bars

    The scroll bar will be shaded bar with about 34 divisions; and a minimum on the left and a maximum on the right. Mousing over the scroll bar changes shading of the scroll bar, and clicking on it changes the value in the input box.
    - There must be an element (typically a DIV) with an ID specified by the `scrollWhere`.
      This element can contain a few special attributes:`<div id="barHere" barWidth="npx" cells="ncells" >`, where `npx` is the width (in pixels) of the scroll bar (the default is 100), and `ncells` is the number of cells (more cells for more resolution, but slower response time), with a default of 30.
  - <step>
    `<step>` is an expansion of `<input type="button">`. It is used to sequentially step through a series of values. `<step>` will create a single button. Each time the button is pushed, a variable is changed and (optionally) a <do> may be executed.

    After the button is pushed (and it's specified variable is changed), the contents of the button is updated. Specifically, the next <step> with the same name as this <step> is used (where "next" is determined by order of appearance).

    Thus, `<step>` is used to create a single button whose actions & text that are meant to be done in a particular sequence: with no skipping steps and no going back.

    Hint: a simple use of STEP is to make an on/off style button; that can be toggled back and forth.

    By default: the value attribute is not used to set the default value of the button (the button's text when the form is loaded).
    Instead, when a form is loaded, the first `<step>` is used to create the initial value of the button.
    However, you can override this.

    Syntax:
    <step name="aname" usename="varname" value="avalue" do="fomname" style="a style" close="0/1" useFirst="logical_equation" > text </step>
    where:
  - name="aname" : specify what variable to change If name=".", do not change a variable. You can still specify a `DO,` or a `RESET.`
  - value="avalue" : value to set the variable to
  - group="gname" : the "group" this STEP belongs to. Optional. If not specified, use the value ofthe 'name' attribute. Thus, by appropriately specifying group, buttons in a sequence (<step>s with the same group attribute) can set the value of more than one variable (ie.; `STEP` elements with the same `GROUP` can have different `NAME` attributes).
  - style="a style" : default style used to display the button. If not specified, a generic default is used.
  - do="formName" : optional. If `<step>` contains a `do="formname"` attribute, then clicking on the button is like clicking on a submit: the value of this radio button is set, and then the formname `<do>` is invoked.
    Note that by default the form is not closed: the form area is not hidden.
  - close="1" : Close the form (hide the form area) after clicking this button. Note that a "do" is executed before the form is closed.
  - reset="1" : Reset the steps: after doing (if a "do" is specified) this step, return to the first step in the group (and thereby restart the sequence).
    Thus, `reset="1"` should only be specified on the last `STEP` in a sequence!
  - useFirst="logical equation" : By default, the first step displayed is the first step in the sequence.
    If you set `useFirst="logical equation"`, then this will be used as the first step if the logical equation is true.
    As with any logical equation, you can use control and general variables. Note that general variables are used by default.
    If there is no match, then the first `<STEP>` is used.
  Examples:
  <input type="text" name="NACCEPT" /> The value will be what is entered in the text box (with a default equal to the current value of the NACCEPT general variable) <input type="text" name="FACIALS.control" /> The value will be what is entered in the text box (with a default equal to the current value of the FACIALS control variable) <input type="checkbox" value="1" notValue="2" name="ASK_SOCIOS" /> When the box is clicked, the ASK_SOCIOS variable will be set to "1". When the box is unchecked, the ASK_SOCIOS variable will be set to "2". <input type="radio" name="petNames" value="CAT" />Felix | <input type="radio" name="petNames" value="DOG" />Rover | <input type="radio" name="petNames" value="FROG" />KneeDeep> Create 3 standard radio buttons. <select> <option name="petNames" value="Cat"> Felix </option> <option name="petNames" value="Dog"> Rover </option> <option name="petNames" value="Frog"> KneeDeep </option> </select> `A standard selection box is used.` <radio name="petNames" value="CAT" />Felix</radio> <radio name="petNames" value="DOG" />Rover</radio> <radio name="petNames" value="FROG" />KneeDeep</radio> Three small, readonly, textboxes will be shown. Clicking on them will change the selected value of `petnames`: and the text box will be highlighted. Just as with standard HTML radio buttons, only the most recently clicked textbox will be used. <array name="costMax" nlength="4" size="6" /> A 4 cell, 1 row table, will be created. The m'th (m=1,2,3, or 4) will contain the m'th value of the `costMax` array variable. Each cell contains a changeable input text box. Any or all of these boxes can be modified. The size of each textbox will be 6 characters. Note that m=1 corresponds to the first value (rather then m=0). <step name="whichPage" value="1" do="PagePost" summary="Show page 1"> Show first page </step> <step name="whichPage" value="2" do="PagePost" > Show page 2 </step> <step name="whichPage" value="3" do="PagePost" > Show page 3 </step> <step name="whichPage" value="4" do="PagePost" close="1" summary="Show last" style="color:red"> Show final </step> Create a button whose intial value is "Show first page". When the button is hit, the "PagePost" <do> is executed. Then, the button's value is set to "Show page 2". This continues (hit button, execute PagePost, reset button) until "Show final", which has a red font. When the "Show final page" button is hit, the form is closed (and PagePost is executed). <submit summary="changes made"> Make the changes </submit> <quit> Don't make any changes </quit>

  #### Notes:

  - all the above input, etc elements will have their defaults set, using the current values of the respective variables. Values will be committed only when the `SUBMIT` button is hit (or, if a `radio` or `step` element has a `do` attribute).
  - `<do>` will use the committed values to update control panel databases, and then (if instructed) can save server variables and general parameters to the server.

    committed means the variable is temporarily changed, but no control panel (or server) databases are changed.

  - Reminder: the form itself (with the form elements and other HTML) will be displayed within the form area of the control panel.
  <PANEL>
  `<PANEL>` is where you specify the visible portion of your control panel -- that is, what will be displayed on screen. Hence, it must consist of valid XHTML code.

  Several special attribute and special tagnames can be used within a `<panel>`.

  special attributes | By default, all elements of the `<PANEL>` are examined. If one of the following special attributes are found (say, in a `<div>`), an approriate `style` and `doClick` attribute is added. `doForm="formName"` :: when this element is clicked, the `<form>` with a `name` of `formName` will be displayed (in the form area of the browser screen) `doTasks="doName"` :: when this element is clicked, the `<do>` with a `name` of `doName` will be executed `doDisplay="anid"` :: when this element is clicked, the `anid` element will be displayed (or hidden) `doCheck="avar"` :: a checkbox is created. When the checkbox is clicked, the `avar` control variable will be set to 1. When unchecked, `avar` will be set to 0 `checkid="anid"`. Used with `<doCheck>`. If specified, the `<input type="checkbox".. >` element that is created will be given an `id="anid"` attribute. Advanced javascript programs can use this `id` to manipulate the check box (say, with a `.click()`). `doValue="avar"` :: a text input box is created. When the checkbox is changed, the `avar` control variable is updated. `doConfirm="A message"`: Used with `doForm` and `doTask`. If `doConfirm` is specified, than before a `doForm` (or a `doTask`) is processed, a javascript confirm box is displayed (with the `A message`). If `cancel` is clicked, the `doForm` (or `doTask`) will not be processed.
  special tagnames | These special tagnames are used just like they are used in a <form>. `<show var="varname" />:` Display contents of a variable `<if value="ifEquation" > contents... </if>`: Conditional use of `contents` `<monitor> contents </monitor>`: Continual update of `contents`. <monitor> is an alternative to using <updateDiv> task in a `<do>`. For details, see the description in the <form>.

  Details: special attributes
  - For `doForm`, `doTasks`, and `doDisplay`, the contents of the element will be display using a link style. You can specify your own style by including a `class` attribute in the element.
    Hint: to make a , include `class="buttonStyle"`.

    Examples:

    <div doTasks="myTasks1" class="buttonStyle">Do the first set of tasks</div> |
    <div doTasks="myTasks1"> Do the 2nd set of tasks</div> | Do the 2nd set of tasks

  - You can not include `doForm` and `doTasks` in the same element (if you do, the `doTasks` will be ignored).
  - You can specify `doDisplay` with any of the others.
  - You can specify `doValue`, and `doCheck` together: but both are ignored if either `doForm` or `doTasks` are specified.

  #### Special attributes: using a `clickStyle` attribute to change the style after a click

  By default, clicking on a link created using `doForm`, `doTasks`, or `doDisplay` will not cause the link to change its look. Thus, there will be no visual evidence that the administrator clicked on said link.

  To provide such visual evidence, you can use `clickStyle="css_style_stuff"` attribute inside of `doForm`, `doTasks`, or `doDisplay`.
  - `doForm`: After clicking on a link created with `doForm`, the `css_style_stuff` will be applied (to the link's style).
    Special value: `clickStyle="1"` will change the text color to purple.
  - `doDisplay`: After clicking on a link created with `doDisplay`, the `css_style_stuff` will be applied (to the link's style).
    Special value: `clickStyle="1"` will change the text color to purple.
  - `doTasks`: After clicking on a link created with `doTasks`, the `css_style_stuff` will be applied (to the link's style).
    Special value: `clickStyle="1"` or `clickStyle="3"` will:
    1. change the link's text color to green while the task is active
    2. For `clickStyle="1"`: when the task finishes, the link's text color is changed to purple
    3. For `clickStyle="3"`: when the task finishes, the link's text color is changed back to blue

    Special value: `clickStyle="style1 style2"` (style1 and style2 seperated by a space) will:
    1. when the link is first clicked, change add `style1` to the link's style
    2. when the tasks are completed, change add `style2` to the link's style

  For example (using defaults): | <div doTasks="myTasks1" clickStyle="1" >Do this!</div> | Do this! (before clicking) Do this! (when first clicked) Do this! (after tasks are done)
  | <div doDisplay="infoArea" clickStyle="1" >More info?!</div> | More info? (before clicking) More info? (after clicking)
  | <div doForm="changeParams" clickStyle="font-style:oblique;font-size:80%" > Change parameters... </div> | Change parameters... (before clicking) Change parameters... (after clicking)
  In this example, note that styles are additive | <div doTasks="myTasks1" clickStyle="font-size:140% background-color:#ababab" >Do this! </div> | Do this! (before clicking) Do this! (when first clicked) Do this! (after tasks are done)

  #### Notes on the `doTasks`, `doCheck`, and `doValue`

  Reminder: these `<PANEL>` special attributes are used in `<DIV>` (and other) elements within a `<PANEL>` ... `</PANEL>`. They are not used as attributes of the `<PANEL>` element!
- when a `doTasks` is specified, you can also:
  1. specify a `summary="message .."`. This summary will be written to the task history bar.
- Using `doCheck` and `doValue` :
- When `doCheck` is specified: you can also include a `value="n"`, where `n` is either 0 or 1.
- `value="1"` : This is the default. The box will be displayed as unchecked. avar in `docheck="avar"`) will be set to `1`
- `value="1"` : The box will be displayed as checked. When clicked on, the box will become unchecked and the variable name (`avar` in `docheck="avar"`) will be set to `0` Note that it is recommended to initialize variables specified in a `doCheck` in the initialization section of the SPEC file -- and initialize it to match your choice of `value`. That is: if you use the default (of not specifiying `value`), then initialize the variable to equal 0.
- When `doValue` is specified: You can include a `value="aval"`.
  The `avar` control variable will be set to this value (note that `aval` can be any string).
- When `doCheck` is clicked or `doValue` is changed, the control variable (i.e.; `avar`) is immediately changed. That is, in contrast to the `FORM` elements, this change happens without the need for selecting a `submit`.
- You can refer to this `avar` variable just like any other control variable -- i.e.; in a `<do>`, and in a `<show>`. Note that for variables specified in `doCheck` the variable will only have values of 0 or 1.
- Unlike elements specified in a `<form>`: a text box created with `doValue`, or a checkbox created using `doCheck`, will retain it's state (it does not get reset when a `<do>` is executed or a `<form>` is invoked).
- Caution: `doCheck` or `doValue` will overwrite a pre-existing value (if the variable was created earlier).

  #### The task-history bar

  Assuming you used the dSurvey administrative tools to create an instrument (hence are using the default control panel file), the control panel will contain a task history bar. This is where short (1-line) summaries of each task are written.

  Notes on the task-history bar:

  - the `summary` attribute:
    For many tasks and form elements, a `summary` attribute is used to specify messages to write to the task history bar. In this `summary`, you can insert variable values by including words with a syntax of
    `%varname`;
    where a space must precede and follow the `%varname`, and `%varname` by default is a control variable.
  - Default styles are used to display the most recent task, and the history of tasks.

  - On the right-hand edge of task history bar, a running status of sub-tasks is displayed. This is used to inform the administrator of what is happening in the most recently selected task-list.
    In particular, when the count of tasks processed equals the number of tasks in the task-list (both of these values are displayed), then the most recently selected `<DO>/` (say, one invoked by clicking on an element that has a `doTasks` attribute) is complete.
    This can be very handy -- it tells the administrator that it is safe to click on something else!