Creating dSurvey SPEC files || dSurvey extensions: other features

## XHTML extensions for dSurvey

Contents

- 1) Introduction
- 1a) The basics: terminology
- 1b) The basics: outline of actions
- 1c) The basics: element attributes and special tagnames
- 2) Setting values
- 2a) Using the special tagnames
- insert
- repeat
- show
- set
- if
- value
- checkbox
- radio
- display
- doit
- info
- history
- 2b)Reading information from the SPEC file
- Reading <attribute> information
- Using <set> in <attributes>
- Reading <use> information
- 3) Submitting information to the server

- Appendix 1: Variables
- Appendix 2: Specifying equations
- Appendix 3: `Call` equations, and using `If` logic
- Appendix 4: Using `<value>`, `<checkbox>`, and `<radio>`
- Appendix 4a: Using `<value>`
- general features
- fancy features
- Appendix 4b: Using `<radio>`
- Appendix 4c: Using `<checkbox>`
- Appendix 4d: Using `<doit>`
- Appendix 4e: Working with change & click

1) Introduction
The dSURVEY software package supports "modular" surveys. By "modular survey", we mean a survey instrument that is built using discrete blocks of XHTML code -- each of these blocks is what we call a "module". Building with these modules is, put too simply, a matter of listing what modules comprise the contents of the survey instrument, and specifying when and how to display each of these modules.

Furthemore, modules can contain dSurvey's XHTML extensions that give the session administrator fine control over what actions should be taken at various times. This allows for customization of web pages, allowing participants to see individual specific information that are easily changed form round to round.

Basically, the use of modules allows for a relatively coarse dynamic control. The use of dSurvey's XHTML extensions with modules gives a much finer dynamic control.

In this document, we describe how to use the XHTML exensions to make these modular survey's highly dynamic. The capabilities provided by these extensions include:

- Displaying participant specific information
- Setting participant specific values, that control what input's the particpant can enter
- Selectively displaying XHTML code, as a function of changeable parameters.

This document will focus on the most useful and commonly used features. If you are interested in some of the more obscure features (many of which are relics of earlier implementations of dSurvey, hence are somewhat deprecated), you can view other features guide.

Please note that these extensions are designed to complement, substitute, and otherwise work with dSurvey's SPEC ("modular survey specification") files.

1a) The basics: terminology
dSurvey's XHTML extensions are designed to facilitate dynamic modification of what the particpant's browser displays.

> - Modifications include changing, saving, and submitting the values of XHTML elements.
> - These modifications are based on the values of session variables, and on user input.
> - Modifications can be made immediately after a group is displayed, when a user inputs information, or when a user submits information.

> - To specify these modifications, the elements are coded with special tagnames.

Let's elaborate on the terminology. Note that some terms are further defined in the SPEC documentation.

XHTML elements | An XHTML element is just an HTML element, that follows case sensitivity and other XHTML rules. To save typing, let's drop the XHTML and just call them elements. Elements have the following structure: `<tagname attribute="attribute value > contents </tagname>` .... or, `<tagname attribute="attribute value />` the `content` may include text and other XHTML elements the `tagname` can be one of the HTML tags; such as `p` or `em`. Or, it can be one of dSurvey's special tagnames. `attribute="attribute value"` are attributes used by the element. Note that you can have zero, one, or many different `attribute="attribute value"` in an element. Note also that `attribute value` must be "quoted". Examples of attributes are `value`, `class`, and `style`. In addition, a dSurvey uses a number of extended attributes are used.
special tagnames | dSurvey recognizes a few special tagnames. These are `<tagnames>` that are not part of HTML. Examples of dSurvey's special tagnames include `<repeat >` and `<show>`.
XHTML element values | The value of an element is what is displayed. What is displayed depends on the tagname: `input` and `option`: for `input` and `option` tags, the value is typically specified in the `value` attribute. Usually, this is a value displayed in an input box, that a participant can either change or just look at. Or it is the text of a push button that the participant can click. `div` and `span`: for `div` and `span`, the value is the `contents` -- the stuff between a `<div>` and its `</div>`. Sometimes this is referred to as the `innerHTML`.

1b) The basics: outline of actions
A short review:

> dSurvey XHTML extensions toolkit works with SPEC files. SPEC files control what & when groups are displayed. SPEC files also specify the contents of a group. This content is typically defined using modules. These modules consist of XHTML, which contains elements that you may wish to customize. The dSurvey XHTML extensions allows you to modify these XHTML elements.

Specifically, the dSurvey XHTML extensions are applied to a newly displayed group. That is, upon display of a group (say, due to button event occurring), the dSurvey XHTML extensions are processed.

The following outlines the kinds of actions supported by dSurvey's XHTML extensions:

- Setting values: Set the values of elements that have special attributes, or specified using special tagnames. These values are often dynamic: they can depend on the current values of session variables.
- Reading values: dSurvey supports a variety of extensions to the HTML form input capabilities. These extensions, that are typically invoked using the special tagnames, facilitate some common display touches (such as boxes around radio buttons), and also make it easy to build in responses to user inputs (for example: message popups when an input box is changed or a button pushed).
- Submitting information to the server: submission to a server occurs when a submit event occurs. The values can include user inputs, as well as dSurvey variables (say, variables that are modified after an input box is filled in).

1c) The basics: element attributes and special tagnames

- In the spirit of seperating content from display, and since there are circumstances where an element may contain lengthy attributes, it is often preferable to define attributes of the XHTML elements (specified in your module) using the <attributes> section of your SPEC file. Note that these can be standard vanilla attributes, such as CSS style attributes or `<table>` parameters.

- dSurvey XHTML extensions are specified using special tagnames

  When defining the special tagname elements, it is often preferable to define the contents of the element using the <use> section of your SPEC file.
  Note that for obscure coding reasons, attributes of special tagnames should not be specified in <attributes> .
- In many cases, instead of using a special tagname, you can use the somewhat deprecated special attributes. As a rule of thumb, the special tagnames are easier to use, and have more predictable effects. Therefore, unless there is a good reason not to (say, your editor supports html attributes but not xml tags) we recommend using special tagnames when possible.

2) Setting values
In this section, we describe how you can use the XHTML extensions to dynamically modify the content of your document.

In particular, when a group is displayed, a number of steps are taken. In order of occurence, these are:

1. The SPEC file determines which modules to display, and in which order. These modules are written to the client's browser (where they are subject to further modification).
2. Minor setup: including suppress the context menu use of the right mouse button, closing old popup windows
3. Use <calls> to call functions, and to the value of dSurvey variable using equations. It is often useful to set dSurvey variables by evaluating equations and calling functions. These modified dSurvey variables can then be displayed directly, or they can act as control variables that determine what blocks of XHTML to display. Using the section of the
4. Process special tagnames.
5. Using <attributes> to set attributes (and values) of elements.

Note that other secondary features (often somewhat deprecated) are also processed: these will be noted as needed. For a complete description of these secondary features, see the secondary features guide.

2a) Special tagnames
dSurvey supports several elements with non-standard `<tagnames>`:
insert, repeat, set , show , if , value, checkbox, radio , display, doit, info, history
In many cases, especially when repetition with complex logic is needed, the use of these special tags may be convenient, if not essential. Do note that by using these special tags, you are deviating quite a bit from standard HTML syntax. There is no obvious reason why that is a problem.

#### The special tagnames

tagname | description
--- | ---
- `<insert module="modname" okSkip="1" after="1" />` | Insert the contents of a module. As with all these `action tags` the `<insert ... >` element will be removed. Thus: `<insert module="amodule" >` is replaced by the contents of the `amodule` module. Notes: If the `amodule` module does not exist, an error occurs. However,, if `okSkip="1"` is specified, then the `<insert>` is just skipped (nothing is inserted, and no error occurs). This can be useful when used with `<repeat>` to insert a list of modules (say, as created by a sequence of `<update>` -- see below). Note that the module can contain any XHTML code, including `<tr ... >` and `<td ... >` The module can contain other action tags, and can reference variables. Technical note: `<insert>` can be processed when the document is first loaded, or as they occur. By default, `<insert>` are processed when the document is first loaded. In contrast, all other special tagnames are processed in the order of appearance. Thus: `<insert>` is processed before any other special tagname. If `after="1"` is specified, then `<insert>` is processed as it appears (that is, it is treated just like any other special tagname). Why does this matter: By processing `<insert>` first, you can properly use an `<insert>` inside of a `<repeat>` (the indices within an `inserted` module will be properly converted to numeric values). Example: <table border="1"> <repeat value="ij=1,4"> <insert module="goo1" /> </repeat> </table> and if the `goo1` module contains: <tr> <td> row <show var="ij" /> </td> </tr> Then the result would be:
  row 1
  row 2
  row 3
  row 4
By processing `<insert>` in sequence, you can use `repeat` to include a sequence of modules. Example (say, used in a module that is displayed using a `<popup>`): <repeat do="ith=1,nUpdates" > <br/> <show var="i" /> <insert after="1" module="uList[i]" /> >/repeat < Or, to skip modules that haven't yet been created: <insert after="1" skip="1" module="uList[i]" />
`<repeat do="loopvar=istart,iend,istep" > xhtml code </repeat>` | Repeat (replicate and concatenate) all the xhtml code between the `< repeat >` and the `</repeat >`. This can include anything, including other special tagnames. In particular, you can nest `< repeat >`. The `value="loopVar=istart,iend,istep"` specifies the start, end, and steps of the loop variable. #### Special Feature: changing the name attribute Within a `<repeat>`, all elements are examined for a `name` attribute. If an element has a `name` attribute with a syntax of `aname[loopVar]`, then the `loopVvar`'s value will be replaced by the current value of the `loopVar`. Example: if `do="avar=1,3"` is used, and this is the second iteration (so `avar=2`), then then a `mooName[avar]` in `name="mooName[avar]"` will be replaced with the value of the `mooName[2]` dSurvey variable. Note that if you nest `repeat`, you can also use `aname[loopVar1,loopVar2]` to read the value of a matrix variable.. #### Special Feature: customizing styles with `addStyle` Within a `<repeat>`, all elements are examined for a `addStyle` attribute. If an element has an `addStyle` attribute, the value of `addStyle` will be used to customize the style of the element. In particular, the style attributes specified in `addStyle` will be parsed, and dSurvey variables will be replaced by their current values. These style attributes will then be appended to a pre-existing `style` attribute (or a `style` attribute will be created if none exists). Syntax... addStyle="styleAtt: avar ; ... " where... `styleAtt`: a style attribute, such as `background-color` or `font-size`. `attValue`: the value for this style attribute. `attValue` can contain any dSurvey equation: it can be a number a single-quoted (') quoted string, a dSurvey varriable, or a concatenation (using `$+`) of numbers, strings, and dSurvey variables. In particular, you can use dSurvey array variables, and use the loop value as the index of this array. Note that you must not include `;`, or `"` inside of `attValue`! Note: attributes specified by `addStyle` will be added to a pre-existing `style` attribute. Example... Assume `colorList` is an array with values:`colorList[1]='red', colorList[2]='blue'` `myIndent` is an array with values:`myindent[1]='5%', myIndent[2]='10%'` rIndent is a dSurvey variable (say, set in a CAP file) with a value: `50` then: <repeat do="jvar=1,2" > <div addStyle="font-size:110 $+ '%' ; margin-left: myIndent[jvar] ; margin-right: rIndent $+ 'px '; " > This is <span style="background-color:gray" addStyle="color:colorList[jvar];" > message </span> <show var="jvar" /> </div > </repeat > will be converted to <div font-size:110% ; margin-left:5% ; margin-right:50px ; " > This is <span style="background-color:gray; color:red"> message <span> 1 </div > <div font-size:110% ; margin-left:10% ; margin-right:50px ; " > This is <span style="background-color:gray; color:blue"> message </span> 2 </div > Note: the create directive is a mostly deprecated alternative to `<repeat>`.
`<show var="varname" anatt="attVal" noSpan="1" />` | Show the value of a dSurvey variable. Alternative syntax: `<show att="attVal" /> varname </show >` Any attributes specified (using one or more `anatt="attVal"`) in the `show` will be used when showing the value of `varname` -- this includes `style`, `class`, etc. However, if you specify `nospan="1"`, than the value will be displayed is -- without any style. Basically, `<show>` will read the variables value, and insert into the web page a `<span>` (that can have `style` and other attributes) that contains this value. `noSpan=1` suppresses this `<span>` (only the value is inserted into the page).
`<set anatt="attVal" > equation list </set>` | Equation list can contain a list of equation, each on its own line. These equations can use `<repeat>` loop variables (the current value of them will be properly read). Note that `<set>` can be used to change screen display (i.e.; as an alternative to `<show>`) -- all equations without an `=` will be concatenated and displayed. When values are being displayed, attributes specified in the `show` (using one or more `anatt="attVal"`) will be used -- this includes `style`, `class`, etc. Note that if no value is to be displayed, attributes are ignored. There are several ways that dSurvey enables evaluation of equations and functions. For example, the setValue special attribute is a mostly deprecated alternative to `<set>`
`<if value="logical equation" > xhtml code </if>` | If the logical equation evaulates to true, then the xhtml code between the `<if>` and its `</if>` will be used. Otherwise, it is discarded. As with `<repeat>`, the `<if>` (and `</if>`) are discarded. Thus, `<if>` can be used to selectively include table cells and table rows.
`<value attName="attValue" use="useBlock" > <value elements> </value>` | Specify an input text box, with lots of fancy options. including cursor keys, graphical arrows, and slider bars. Notes: given their complexity, it is often wise to specify value elements with a use attribute. Variables specified in `<value>` (either local dSurvey variables or variable to be submitted to the server) are changed only after a <submit> event occurs (as specified in the SPEC file). `<value>` is an alternative to using the somewhat deprecated KEYINC, CHECKBOUNDS,and other event handlers. Special feature:Enabling a `busy computing` message. If you specify a `<span>` with an `id="_busyAlert"`, then when `change` is specified (i.e.; equations are run when a value change occurs), this `span` will be made visible. Once the equations are complete the `span` will be hidden. This can be used to alert the participant that a long calcuation is occuring, so he should wait. IE bug fix: for some reason (Nov 2010) IE8 will sometimes process equations VERY SLOWLY. Thus, if this `_busyAlert` `span` is specified, after equations have been running for 2 seconds, an alert box comes up that says `Computing...`. This is a gross IE workaround, that we will remove if we ever figure out how to force IE to do an immediate screen refresh.
`<checkbox attName="attValue" use="useBlock" > <checkbox elements> </checkbox>` | Specify a checkbox. input text box, with several fancy options. Notes: given their complexity, it is often wise to specify checkbox elements with a use attribute. Variables specified in `<checkbox>` (either local dSurvey variables or variable to be submitted to the server) are changed only after a <submit> event occurs
`<radio attName="attValue" use="useBlock" > <radio elements> </radio>` | Specify a radio button. Unfortunately, dSurvey modules do not support the use of `<input type="radio" >`. Fortunately, you can use `<radio>` to specify radio buttons, and these radio buttons can have a number of fancy options; such as requiring a selection, extended labels, and surrounding boxes. Notes: given their complexity, it is often wise to specify radio elements with a use attribute. Variables specified in `<radio>` (either local dSurvey variables or variable to be submitted to the server) are changed only after a <submit> event occurs
`<display target="anid" type="atype" useStyle="altStyle" text="amessage" text2="altMessage" hideButton="1" hideContent="0" > XHTML content </display>` | A button (or a link) will be created. When the button (or link) is clicked, the display of the XHTML content will be toggled (between visible and not visible). Note that XHTML content can contain any of the special tagnames. By default, a button is shown displaying a message you select, and the XHTML content starts out not-displayed. However, you can set a number of options.... `text="a message"`: `a message` is displayed: as the (or the text of the link). `text2="a different message"`:optional. If specified, the button (or link) text will be changed whenever the button (or link) is clicked -- the message will alternate between the `text` and the `text2` message (with the `text` message displayed first). `type="link"`: optional. If specified a url-style link is used (rather than a ) `useStyle` : optional. A css style string. If specified, and `type="link"` is specified, than the `altStyle` is used to display the link (instead of underlined blue). `hideButton="1"` : optional. If specified, then the button (or link) will be hidden after it is clicked. Note that if `hideButton="1"` is specified, `text2` is ignored. `hideContent="0"` : optional. If specified, then the XHTML content will start out being displayed. Otherwise (i.e.; if not specified), this content will start out not being displayed. `target="anid"`:optional. If specified, the element (i.e.; a `<div>` with an ID of `anid` will be toggled. Thus, the XHTML content is ignored (it will be removed). Note that if `target` is not specified, then the XHTML content will be moved into a new `div`, and this `div` will be displayed (or hidden) when the button (or link) is clicked. Examples: <display text="Display secret stuff! text2="Undisplay..." > <p /> This is my secret stuff, for version <show var="theVersion" />. </display > <div id="goo1"> <table border="2" cellpadding="5"> <tr><td> <display target="goo1b" text="Hide some boring stuff!" hideButton="1" /> <display target="goo1" text="Hide all boring stuff!" /> </td> <td> <div id="goo1b" style="border:2px solid blue">Some boring stuff! </div> </td> <td> <div style="border:2px solid blue">Some other boring stuff! </div> </td> </tr> </table> </div>
`<doit attName="attValue"" type="link" use="useBlock" text="a message" > equations </doit>` | A button (or a link) will be created. When the button (or link) is clicked, the `equations` will be evaluated. `type="link"`: optional. If specified a url-style link is used (rather than a ) `text="a message"`: `a message` is displayed: as the (or the text of the link). `hide="1"` :optional. If specified, then the button (or link) will be hidden after it is clicked. `attName` : other attributes. Note that `style`, `class`, can be used to display the text, and `title` can be used for a mouseover title. The equations will be evaluated when the click occurs. Thus, the most recent values of session variables will be used -- including variables modified by other special tagnames (say, a variable modified via a `<change>` in a `<value>`). And everytime the button (or link) is clicked, the equations will be reevaluated. Note that `<doit>` will process equations and set values immediately -- in contrast: for `<value>`. `<checkbox>`, and `<radio>`, values are set only when a `<submit>` event occurs (as specified in the SPEC file). Reminder: You might find it cleaner to specify the equations used by `doit` by using a `use="useName"` attribute that points to a <use> (rather than specifying equations in the `doit` container). More details on using <doit>
`<info attName="attValue" > message </info>` | `<info >` makes it easy to add help links to selected elements. Help links are standard links (underlined blue text) that when clicked cause a help message to be displayed in a help box. The help message is specified by specifying the name of an existing module (which can contain special tagnames). Note that since the help message is displayed when clicked, you can't successfully use `<repeat>` indices within a module used by `<info>`. Example: <info infoName="Tip1" title="Various tips and tricks" helpWord="Tip Number 1 " noHelpBox="0" > Item1 Tips </info> Note that Item1 Tips will be a clickable link, displayed using an underlined blue font. `infoName`: The name of the module containing the help message. If no such module exists, an error message is displayed. `title="short message"`. Optional, if specified, a title is added to the link, consisting of the `short message`. This title is displayed when the mouse is over the link. `noHelpBox="1"`: By default, help messages are written to the help box, which is a gray box in the middle of the main window. When this box is clicked on, it disappears. If you are displaying help in a popup window, this can be confusing -- the help will be in the main window, not in the popup. In these cases, you can specify `noHelpBox="1"`. This causes a simpler help message to be written, consisting of the text but not the HTML markup (of the selected module). This will be written to a gray box at the top of the window (that will be overwritten if a new help link is clicked) `helpWord="short phrase"`. Optional. Only used if `noHelpBox="1"` -- it is used at the beginning of the help message: `Help for short phrase :` There are several CSS definitions you can change (in `svyLibE2.css`) that allow you to customize display: `styleInfoLink`, `styleInfoLink_header` and `styleInfoLink_body`
`<history name="historyName" > a message </history>` | The `<history>` special tagname is designed to be used with the <history> SPEC file element. The `<history>` special tagname will create a button that, when clicked by the participant, will open a popup window and display a History table -- that contains variables from prior rounds specific to each participant. The text of this button will be the `a message`. The `name="historyName"` attribute is optional. If specified, it should match a `name` attribute specified in the SPEC file `<history>`. Basically, you can specify several different History tables, using different `name` attributes (in both the special tagname and in the spec file `<history>` elements. You can specify `style` and `class` attributes in the `<history>` special tagname. If you do not specify a style `style` or a `class`, a default button style is used (which can be modified by changing the `historyButton` style in `svylibe2_globals.js`). To create a link, use `class="historyLink"`. For more details on specifying, building, and displaying a `simpleHistory` see the SPEC guide.

2b) Reading information from the SPEC file

To improve readability, instead of specifying elements within a special tagname, or in the attributes of the special tagname, you can use the SPEC file.
In particular, you can use the

- <attributes> section, and the
- <use> section The next two sections contain short descriptions of `<use>` and `<attribute>`.
  Reading information from <attributes>
  You can use this elements specified within `<attributes>` to specify normal attributes (such as `style`).
  Example:
  Including this in your module... < ul > <li> <set style="color:red;font-size:120%" > cost_min[irow] </set> </li> <li> <set style="color:blue;font-size:120%" > cost_max[irow] </set> </li> < /ul > is the same as including this in your module.. <ul > <li> <set name="li1"> cost_min[irow] >/set> </li> <li> <set id="li2"> cost_min[irow] >/set> </li> </ul > and including this in your <attributes>: <li1 name="1" > <style> color:red;font-size:120%" </style> </li1 > <li2 > <style> color:blued;font-size:120%" </style> </li2 >
  Setting values using a <set> in <attributes>
  Using `<set>` inside of a `<attributes>` is deprecated. Use a `<set>` with `<use>`

  As described in the SPEC guide, you can use `<set>` inside of an `<attributes>`

  Reading information from <use>

  The `use` attribute, when included in special tagname elements, will read information from the appropriate portion of the <use> section of your SPEC file, and then use this information to specify the `contents` of a special-tagname (such as `<value>`).

  Example:
  Including this in your module... <value use="valSpecs"> <title> My offer </title> <submitName> OFR1 </submitName> <start> 12 </start> <change> foo=foo+1 alert(' Your foo is ' $+ foo) </change> </value"> is the same as including this in your module.. <value use="valSpecs"/> and including this in your <use>: <valSpecs > <title> My offer </title> <submitName> OFR1 </submitName> <start> 12 </start> <change> foo=foo+1 alert(' Your foo is ' $+ foo) </change> </valSpecs>
  Example:
  Including this in your module... < ul > <repeat value="irow=1,8=" > <li> <set style="color:red;font-size:90%" > cost_min[irow] </set> </li> </repeat> < /ul > is the same as including this in your module.. <ul > <repeat id="rep1" > <li> <set name="lix"> cost_min[irow] </set> </li> </repeat> </ul > and including this in your <use>: <rep1 > <value> irow=1,8 </value> </rep1 > and including this in your <attributes>: <lix name="1" > <style> color:red;font-size:90% </style> </lix >
  Example (using <set> with <use>) ....

  Instead of ... | <show style="color:red" var="cost1" /> <if value="size gt 10" < <set style="color:blue"> newCost=figCost(size,10); newcost </set> </if> <if value="size le 10" < <show style="color:blue"> var="lowCostMessage" /> </if>
  you could specify ... | <set use="idCost" id="idCost" /> <set use="idSize" id="idSize" />
  and define the following in your SPEC file ... | <attributes> <idCost> <style> color:red </style> </idCost> <idSize> <style> color:blue </style> </idSize> </attributes>> <use>> <idCost> cost1 </idCost> <idSize> <if value="size gt 10" > newCost=figCost(size,10) newcost </if> <if value="size le 10" > lowCostMessage </if> </idSize> </use>

  3) Submitting information to the server
  Submitting information to the server is done with a submit event action. The `submit` event action instructs the client to submit values to the web-server. Or, `submit` can be used to accumulate variables to be submitted to the server, say after several `submit` events where each event is associated with answers to different questions.

  But how to tell the client which variables to submit? There are several ways:

  1. In the `submit`, specify a <save> that lists `submitName1=session_var1` pairs ;
     where each pair specifies a variable (with the name `submitName1`) and its value (the value of the `session_var1` session variable).
     If you want to use the build a data dictionary utility, all `submit` variables should be specified using this method!
  2. When using a special tagname (`value`, `radio`, or `checkbox`), specify a `<submitName>` (as a child node). Note that this `submitname` may be structured as an array (i.e.; `cost[ith]`, where index values (the `ith`) will be resolved (using dSurvey variables) and the resulting name (say, if `ith=3`, `cost[3]`) used in the submission to the server.
  3. All elements with an attribute of `submitName="aVarName"` will have their values submitted, using the `aVarName` as the variable name. Note that the special elements (`value`, `radio`, and `checkbox`) elements will not be checked for this `submitName` attribute.
     Example: `<textarea rows="3" cols="80" submitName="myComment">>comment here </textarea>`
  For details on how information is sent to the client, see savingResults.htm.

  Appendices

  Appendix 1: variables
  The dSurvey XHTML extensions allow you to use several different kinds of variables.
- session (dSurvey) variables and arrays: `varname`
  By default, variable names are assumed to be session (dSurvey) variables.
  Technical note: if you start a variable name with the `%` character, the variable will be treated as a session variable. Since this is the default, there is no real need to do this.

  Important note: the longevity of session variables is controlled by the SPEC file. In particular, by the `priors` attribute of <params>.

  Arrays: You can specify elements of a session array by using `arrayName[i]`. For example, to specify the 3rd element of the `myCost` array, use `myCost[3]`.

  You can create a several element array by using the `Array` function: as in `Array(val,val2,...)` .

  There are several session variables that are always available: | `_instrument` : name of this instrument (that this session is created from) `_sessionName` : the session name `myID` : client ID `myNAME` : client name `myNICKNAME` : a nickname (if `GET_NICKNAME=0` is specified in the instrument descriptor file, this will be blank). `myCONTACT` : contact information (if `GET_CONTACT=0` is specified in the instrument descriptor file, this will be blank). `myREFID` : client's reference ID (might be '') `_groupNameFull`: the name of the currently displayed section and group name, using a syntax of: `section.group`
  Debugging note: To view the values of all the current session variables, you can call the `Show_Variables()` function. For example: <set> Show_Variables() </set> `Show_Variables` will create a new window, and will display a table with all the currently defined session variables (for this participant)

- prior session variables and arrays: `varname.nRound`
  Prior session variables are session variables that were set in a prior round. These prior variables are created when a `<params priors="BOTH" />` is specified in a `section` (or `priors="SAVE"`). They can also be specified in a client accessible parameters file (for example, containing results of the most recently completed round).

  Prior variable are identified by a `.roundNum` after a `varname` (or after a `arrayName[ith]`). The `roundNum` is the round number to use. It can be a number (i.e.; `cost.3`, a global variable (i.e.; `cost.bestRound`), an element value (i.e.; `cost.@askRound`), or an attribute value (i.e.;`cost.#irnd`).
  It can not be another prior variable (i.e.; it can not be `cost.wasBest.3`).

  Examples...

- `myCost.3` : value in round `3` of the `myCost` variable
- `subFee[2].4` : value in round `4` of the element `2` of the `subFee` array.
- `myCost.jround` : lookup the value of the `jround` dSurvey variable, and find the `myCost` variable saved under its round

  Recent prior values: if you do not specify the `roundNum`, then the recent round is used. recent refers to any prior value that has been saved; say, a prior value read from a client-accessible parameters file.

  When a prior value is saved, its value will be saved twice: once to the `round number` (specified in the `.roundNumber`), and to this recent round.

  Thus, a `myCost.` would refer to the mostly recently saved prior value of the `myCost` variable.

  When a new section is started: if a section has a `<params>` with a `priors="reset"` or `priors="both"`, the current values of session variables will be discarded.

  If `priors="BOTH"`), before they are discarded, these current values will be saved -- they are saved as the recent prior values (as well as being saved as round-specific prior values).

  Example .

  - Assume that round 9 completed successfully.
  - Round 10 then is started -- by invoking a `<section>`.
  - This section includes a `<params priors="BOTH" />` -- so a new CAP file is downloaded from the server.
  - This CAP file contains: `<POINTS.9> 105 </POINTS.9>`
  - `points.9`
    would yield a `105` (since it refers to the round 9 value of the `points` variable.
  - `points.`
    would yield a `105` (since it refers to the most recently saved value of the `points` variable.
  - Round 10 concludes, round 11 begins, and the client-accessible parameters file specifies: `<POINTS.10> 235 </POINTS.10>`
  - `points.9`
    would yield a `105` (since it refers to the round 9 value of the `points` variable.
  - `points.`
    would yield a `235` (since it refers to the most recently saved value of the `points` variable).

- The value attribute of an HTML element: `@elemName`
  If the first character of a variable name is `@`, then the variable name is treated as the `name` of an XHTML element. If an HTML element with this `name` exists in the currently chosen group, its value is found and used.
  - If the requested element does not exist in the current group (that is, in what will be displayed on the browser screen), a blank is used.
  - Alert: the `name` attribute (of the XHTML elements) is used for matching, not the `id` attribute!
  What is the value? The value that is retrieved depends on the type of the HTML element:
  1. For `input` and `option` HTML elements: the `value` attribute is used.
  2. For `div`, `span`, and other HTML elements: the `innerHTML` is used (i.e.; the content between its `<div>` and its matching `</div>` ).
  A Shortcut: If you use `@` by itself (with no variable name), the value of the current element will be used.

  Special Feature: array like names:

  You can use array like element names. For example: `allNames[var1]`.
  These internal elements will be processed, with session and other variable converted to their values.

  Notes:
- Example: if `var1` is a session variable with a value of `3`, then the `allNames[var1]` is converted to`allNames[3]` (thus, the value of the `allNames[3]` element will be used/changed).
- multi-dimensional names (such as `allNamesB[var1,var2]`) are permitted.
- You can include element names as elements. Thus, the following is permitted:`@askname[@myrow,@mycol]`

- The value of an `attribute` of an HTML element: `#varname`
  `#varname`: If the first character of a variable name is `#`, then the variable name is treated as an `attribute` of the current element. If no such attribute exists, a blank is used. Note that in some cases (noted below), there will not be current element -- in those cases, using a `#` results in a blank string.

  A Shortcut: If you use `#` by itself (with no variable name), the value of the `idx` attribute (of the current element ) will be used.

  #### The current element

  As noted above, it is possible to retrieve and use information on the current element: such as its value, or the value of one of it's `attributes`.
  But what is this current element ?

  Basically, the current element is ...

  - the XHTML element that a `setValue` is an attribute of
    or
  - the XHTML element that is being modified via a `<set>`
  In other cases (such as when evaluating section specific equations) there is no current element, so attempting to access information on a current element yields a blank string.

  #### Caution! Control panel variables are not the same as the client's variables

  When writing a control panel, one can access variables from a variety of sources. These include `general`, `control`, `user`, and `reference` variables. However, on the client side (the modules, etc) there is no distinction between the source of a variable.

  Thus, you should not include suffixes (such as `.G`) when specifying variables in a dSurvey modules (or a SPEC file).

  #### Warning on the use of undefined variables

  As a programming aid, dSurvey will display a message (using a Javascript `alert` box) whenever an undefined global variable (or an undefined history variable) is referenced (i.e.; in a `<show>`). This warning will have no effect on the operation of dSurvey, but it may confuse participants!

  We recommend removing such references to undefined variables (say, by setting the offending variable in the `initialization variables` section of the `SPEC` file). However, if you can't avoid such references, you can disable this `strong typing` by using either of these two methods:
  1. change the `strongTyping` variable in `/dsurvey/client/defaultStart.html` (change it to zero)
  2. set the `debug_mode` variable (in the instrument's descriptor file) to `0`.
  The second method is actually safer -- changing `defaultStart.html` will effect all of your instruments (unless you are clever and assign an instrument specific `HOME_PAGE`).
  In addition, turning off debugging is a good idea once you are sure the instrument is bug-free (turning off debugging speeds up performance a bit, and reduces some clutter).
  Appendix 2: equations
  dSurvey XHTML extensions & SPEC Files support a javascript-like equation processor. This is used to set variables, to call functions, and to specify logical equations. The following describes the capabilites of the equation processor.

  Equations may contain ...

  - variable names -- session s (including survey array elements), element names (prefaced with @) , and (in some cases) attribute names (prefaced with a #)
    Two reserved variables can be used: PI and E (case insensitive).
  - numeric values. You can use scientific notation for your values: i.e.; 1003 or 1.003e3 , 0.04 or 4.0e-2
  - 'quoted strings'
  - math operators: + - / * ^ \
    Note that ^ is expoentation (2^3=8), and \ is throw away remainder division (5\2=1)
  - Javascript math functions, such as `Math.ceil(xx), Math.Max(a,b), Math.round, Math.exp, Math.min, Math.pow(a,b), Math.sqrt`
  - ( ) to group terms together
  - logical operators: == != EQ NE GE LE GT LT
  - more logical operators: OR AND XOR
  - special functions: EXIST NOT IN
  - Other functions, that may use multiple arguments
  - - signs to indicate negative value (of a variable, value, or function)
  - Notes:
  - Functions are fully recursive. That means that arguments of functions can also be equations, that may contain functions etc!
  - Functions will be called with string arguments, so whatever value (string or numeric) the arguments are evaluated to, they converted to strings before the function is called.
  - The 2-3 letter logical operators MUST be preceded and followed by spaces. Otherwise, spaces are optional.
  - Tabs and CRLFs are converted to spaces
  - Strings can be used, if embedded in ' quotes.
    If you 'quote' a number and use it in normal math calculations, the number will be used.
    If you quote a non-numeric string and use it in normal math calculations, a NaN is returned.
  - You can concatenate strings using $+
  The order of precedence is (with left to right precedence for operators in the same set):
  1. variable names (resolving values of variables)
  2. functions and ( ). Note that arguments are processed recursively, using these rules
  3. ^
  4. * / and \ `( \ is modulus division: 5\2 = 1 )`>
  5. + and -
  6. == != EQ NE GE LE GT LT
  7. AND OR and XOR. Hint: instead of AND and OR, you can use & and |
  8. $+ (string concatentation).
  Special functions:
  - `NOT(XX)`: Returns the logical NOT -- if xx (where xx is any valid equation string) =0, true is returned. Otherwise, false.
  - `EXIST(XX)` : Returns 1 if the XX variable exists, 0 if it does not.
  - `IN(needle,haystack,useCase)` Returns word in haystack (starting at 1) if `needle` (a word) is in `haystack` (a space delimited list of words). 0 if no match. `useCase` is optional: if it is a `1`, a case-sensitive search is used (otherwise, a case-insenstive search is used).
  - For `NOT` and `EXIST`
  - XX is a session variable (i.e.; `myIncome` or `%myIncome`): existence means variable was defined previously
  - XX is an element (i.e.; `@myCost`): existence means element with this name exists.
    Note: for equations within a `<params>`, `Exist(@elemName)` always returns `false`.
  - XX is an attribute (i.e.; `#aCharge`): existence means attribute with this name exists.
    Note: for equations not in a `<set>` or `setValue`: `Exist(#attName)` always returns `false`.
  - `htmlSurround(tagname,string)` : returns a string `<tagname>string</tagname>`
    Example: `htmlSurround('em','earnings=' $+ myEarnings)` could return: `<em>earnings=100</em>`
    `htmlSurround` is useful way to create customized strings containing html markup, using a `<set>` (since `<set>` does not like html markup)
  Examples...
  1.1e3 * ( -34.04 + myFunc2(109/3 , 5^2) ) X1 Ge 10 and X1 le 20 messName= 'Full name: ' $+ (firstName $+ ' ' $+ lastName)
  Logical equations:

  dSurvey XHTML extensions & SPEC files use `if` to control processing. `IF` works by evaluating a `logical equations`, and processing (say, setting a value of an element) if the logical equation is `true`.

  Logical equations are simply equations that contain the logical operators (along with any of the other math operators, etc).
  These are evaluated, and the value (true or false) of the entire equation is returned (with a `true` value telling the `if` to continue processing).

  Actually, logical equations don't need to contain any logical operators. In this case, the value of the equation is first computed; and any non-zero value is treated as true, and zero is treated as false.

  Appendix 3: `Call` equations, and using `If` logic
  A major strength of dSurvey XHTML extensions & SPEC files is the ability to dynamically modify content. This dynamicism is largely based on the capability of computing equations, calling functions, and of doing this under logical control. This section outlines the several places where these capabilities can be exercised -- an exercise that typically uses `call` and `if` directives!

  - A review of the the use of If
  - A review of the ordering of equation evaluation
  Appendix 4: Using `<value>`, `<radio>`, and `<checkbox>`

  Appendix 4a: Using `<value>`
  Syntax:
  <value attributes="..." > <tagname> ... </tagname> // specify fancy features using special tagnames </value>
  `<Value>` is used to set up an `<input type="text">` box, with a number of fancy features. These features include:
  - Using graphical arrow keys to increment/decrement numeric values
  - Using a slider bar to select a numeric value between two extremes
  - Using cursor arrow keys to increment/decrement numeric values
  - Checking for maximums and minimums

  These features are specified in seperate elements between `<value>` and `</value>`. Or, they can be specified in attributes in the `<Value>`.

  Note that `<value>` can contain standard HTML attributes (such as "id", "name", "size", "style", "class", "accesskey", and "maxlength") which will be added to the `<input>` that is created. However, you should not specify a `type=".."` or a `value=".."` attribute: they will ignored.

  There are several general features, and several fancy numeric entry features

  The general features

  Specified using an `<element>` between `<value>` and `</value>` (possibly added via a `use`) | Specified using an `attribute` in `<value>` | Description
  --- | --- | ---
  `<isNumber show="1"> flag </isNumber>` | `isNumber and isNumber_show` | Accept non-numeric entry? In all cases, if a number is enter, then "min/max/confirm_min/confirm_max" may be checked. The value of `flag` can be: `0` or `N` : anything can be entered. `1` or `Y` : the default. MUST be a numeric entry, or a ''. If a non-number is entered, it is converted to prior value `2` or `R` : number is required. Non-numeric entries (including '') are converted to the prior value value. `show="1"` means show an error message if a non-number is entered (ignored if `0` or `N` is used)
  `<submitName>varname </submitName>` | `submitName` | Submit this value to server (when a submit event happens) using this name
  `<submitVar>varname </submitVar>` | `submitVar` | save this value to this dSurvey variable (when a submit event happens)
  `<changeVar>varname </changeVar>` | `changeVar` | save the current value to the varname variable. This occurs after you change a value (enter something in the input field, and then click outside of the input box). That is, it does not wait for a submit event. Note that `changeVar` will save values after their possible modification by equations specified in a change.
  `<`title` > a title </title>` | `title` | mouseover title (when the mouse is over the input text box
  `<start varname="avar">value </start>` | `start` or `start_var` | The value first displayed (this is the default value). If not specified, '' is used If `<isNumber>` equals 2: if not specified, "0" is used. If non-numeric specified, an error occurs If `varname="avar"` specified, `avalue` is ignored. Instead, the value of the `avar` dSurvey variable is used (or a '' if no such variable exists)
  `<allowed show="1"> word list </allowed>` | `allowed` and `allowed_show` | `<allowed>` is used to specify permitted 1 word entries. It also overrides `isNumber.` `word list` should be a space delimited list of permitted values. If the stripped entry does not match a word in this list, the value is not saved; the prior value is used. Notes:

- case insensitive comparision is used
- the comparison occurs `onChange` (not while keyboard entry is occurring) If`show="1"`, then display allowed values if not a match.
  These next 4 are ignored if `<allowed>` is specified, and if the value entered is a number.
  `<min show="1" >avalue </min>` `min` and `min_show` minimum value (default is no minimum)
  `<max show="1" >avalue </max>` `max` and `max_show` maximum value (default is no maximum)

  If `show="1"` is specified, then display a generic error message if a too-large number is entered.

  `<confirm_min value="avalue"> a message
  </confirm_min>` `confirm_min_value` and `confirm_min_message` Ask if an entered value is below `avalue`, using `a message`
  If a message is not specified, then use a default message is used
  `<confirm_max value="avalue"> a message
  </confirm_max>` `confirm_max_value` and `confirm_maxxmessage` Ask if an entered value is greater than `avalue`, using `a message`
  If a message is not specified, then use a default message is used
  These next 2 are used to customize, and to perform other actions.
  `<change>
  equation list
  </change>` Not recommended Equations/etc to execute when the value is changed.
  Equation list can contain alert, confirm, E2_writeStatus, E2_writeAlert, and setting attributes or other element values. This can be used to change the value just input (say, capitalize).
  See working with change & click for the details.

  Note that after `change` is processed, then changeVar will be done (so any changes in the value will be saved to the changeVar variable).

  `<click>
  equation list
  </click >` Not recommended Equations/etc to execute when the input box is clicked on.
  Equation list can contain alert, confirm, E2_writeStatus, E2_writeAlert, and setting attributes or other element values.
  See working with change & click for the details.

  Some fancy features
  For entering numeric values, uou can use these three fancy numeric entry elements; each of which can have "sub-specs" specified (as nested elements),
  - `<key>` : specify if cursor keys can be used to increase numeric values
  - `<arrow>` : specify if graphic arrows (displayed next to the input box) can be used to change numeric values
  - `<scroll>` : specify if a scroll bar (displayed next to the input box) can be used to change numeric values

  Specified using an `<element>` | Specified using an `attribute` in `<value>` | Description
  --- | --- | ---
  `<key>` | key="1" | Use cursor keys to increment/decrement numeric values.
  options used with `<key>`
  `<increment> value </increment>` | `key_inc` | The amount to increment when up arrow, or to decrement when down arrow, is pushed. If not specified, a value of 1 is used.
  `<increment_page> value </increment_page>` | `key_inc_page` | The amount to increment when pgUp, or to decrement when pdDnw, is pushed. If not specified, a value of 10 is used.
  `<esc> value </esc>` | `key_esc` | value filled in when esc hit. If not specified, `<start>` value is used.

- If esc hit and the current value is this `<esc>` value, then change the value to ''.
- Exception: if , on this "2nd esc" value is changed to the `<start>` value
  `<esc>` augments `<start>` -- for example: `<start>``</start>` `<key>``<esc>`10`</esc>``</key>` Then '' is displayed at first, hitting ESC yields a 10, and hitting ESC again goes back to ''.
  .........
  `<arrow> dochange="1" size="nn" >` ``arrow="1"`` Use graphical arrows to increment/decrement numeric values.
  options used with `<arrow>`
  Note: `<arrow />` or `<arrow>` `</arrow>` mean "use the default arrow, in the default location
  `size="nn"` `arrow_size` Size of the images used to display the arrows, in pixels. Default is 20.
  `dochange="1"` `arrow_dochange` If 1, then a click on an arrow will cause the change handler to be called. In other words, it simulates what happens if the value in the text box was re-typed in.

  Thus, using `doChange="1"` presumes that you specified a `<change>` option for this `<value>`.

  Caution: if a participant clicks an arrow rapidly, the load on the client's browser may be onerous (since every click means run the `<change>` equations).

  `<name>arrowName</name>` `arrow_name` If specified, the "base name" of the gif files used as the arrows.
  The currently supported names are:
  `Arrow`, `ArrowGreen`, `Chevron`, `ChevronGreen`, and `FairytaleBlue`
  The default value is `Arrow.`
  `<where>idName</where>` `arrow_where` The location to display the arrows (say, the ID of a `<DIV>`).
  If not specified, a table is created with the box on the left, and arrows on the right
  .........
  `<scroll> show="1" titleOnly="1" >` `scroll="1"` Use a scroll bar to choose a value between two extremes.
  options used with `<scroll>`
  Note: `<scroll />` or `<scroll>` `</scroll>` mean "use the default scrollBar, in the default location"
  `show="1"` `scroll_show` If specified (as an attribute of the `<scroll>`), show value while scrolling (in a small box near the scroll bar.
  It would be better if this was displayed in a floating title box, but for now this will have to do.
  `titleOnly="1"` `scroll_titleOnly` If specified (as an attribute of the `<scroll>`), show value as a floating title. Do not update colors.
  This might be quicker on cpu constrained machines (hence might support more `cells`) Note that `titleOnly="1"'` supresses `show="1"`.
  `<where>idName</where>` `scroll_where` The location to put the scrollbar (say, the ID of a `<DIV>`).
  If not specified, a table is created with the box on the left, and arrows on the right (if specified) and the arrows in 2nd row (underneath both box and arrows)
  `<min>` `scroll_min` Minimum (left) value of bar. Can be greater than min, but not less. Default is `<min>`
  `<max>` `scroll_max` Maximum (right) value of bar. Can be greater than min, but not less. Default is `<max>`
  `<width>` `scroll_width` The width of the scroll bar, in pixels
  `<cells>ncells</cells>` `scroll_cells` The resolution of the scroll bar. Ncells large means higher resolution, but takes more CPU resources.
  The default value is 33.
  Example: If width is 300, and ncells is 50, and min and max value are 1 and 20 then each "cell" is 6 pixels wide, where a "cell" is matched to a value. the resolution is 4 (left most is 1,5,..., right most is 200)
  `<leftColor>rgb
  </leftColor>` `scroll_leftcolor` The leftmost (small) color. The scroll bar color will be a linear trend between the leftColor and rightColor.
  rgb should be in `rrggbb` "hex" format (you do not need the leading #).
  Default color is `#839db8`
  `<rightColor>rgb
  </rightColor>` `scroll_rightcolor` The rightleftmost (small) color. The scroll bar color will be a linear trend between the leftColor and rightColor.
  rgb should be in `rrggbb` "hex" format (you do not need the leading #).
  Default color is `#abcdf0`
  `<fmt>ndec</fmt>` `scroll_fmt` Number of decimal points to use when displaying number. Default is 2. Thus, ndec of 2 means display 10.152 as 10.15

  #### Example...

  <value id="pigs" size="7" style="background-color:cyan" > <isNumber show="1">1 </isNumber> <start>121</start> <title> this is great </title> <min show="1">20 </min> <max show="1">1000</max> <confirm_min value="50">So small? </confirm_min> <confirm_max value="1200">Are you sure you want to use big value </confirm_max> <change> <if value="addme gt 13"> z=confirm(' you have entered ' $+ #value $+ ' after ' $+ svyMiss(addme) $+ ' changes. Are you sure? ') <if value="z eq 0">#priorVal</if> </if> </change> <click> addme=svyMiss('addme') + 1 </click> <key> <increment>0.1</increment> <increment_page>5 </increment_page> </key> <Scroll show="1"> <fmt>2</fmt> </Scroll> </value>
  Appendix 4b: Using `<radio>`
  `<radio>` is used to set up an `<input type="radio">` box, with a number of fancy features. These features include:
  - Require that one of the radio buttons (in a set of buttons) is hit
  - Adding a label to the button
  - Putting a box around this label and button, that will be shaded when the button is pushed
  - Specifying a dynamic button name
  Similar to how <value> is specified, these features are specified in seperate elements between `<radio>` and `</radio>`. Or, they can be specified in attributes in the `<Radio>`.
  Note that `<radio>` can contain standard HTML attributes (such as "id", "name", "style", "class", and "accesskey") which will be added to the `<input>` that is created. However, you should not specify a `type=".."` attribute: it will be ignored.

  ID and NAME can be used to find the attribute. In particular, you can use ID or NAME to assign attributes in the `<attributes>` section of the spec file.

  TITLE can be specified inside of `<radio>` -- it will be displayed when the mouse is over the radio button (but not when the mouse is over the label).

  Simple syntax:
  `<radio name="varname" value="avalue" />`
  is synonymous with `<input type="radio" name="varname" value="avalue" />`. In fact, `<input type="radio" name="varname" value="avalue />` will not work properly in dSurvey modules. Thus, you should use this simple syntax for a standard radio button.

  However, the real advantage of `radio` is its support for a number of useful extensions.
  Syntax:
  <radio attributes="..." > <tagname> ... </tagname> // specify fancy features using special tagnames </radio>
  There are several general features, and several fancy button features

  #### The general features

  Specified using an `<element>` between `<radio>` and `</radio>` (possibly added via a `use`) | Specified using an `attribute` in `<radio>` | Description
  --- | --- | ---
  `<group name="aname" append="varname" />` | `group` or `group`, and `group_append` | Required. Defines the subset of buttons this radio button belongs to (the button group). Only one button, in a subset, can be selected. Basically, `group` serves a function similar to the `name` attribute in a standard `<input type="radio" >`. The `append` attribute is optional. `varname` should be a dSurvey variable name, such as the loop-variable in a <repeat>. The value of `varname` is appended to the `aname` to identify the group. Thus, the use of `append` makes it easy to use `repeat` to specify several sets of radio buttons. Example: if the `nchoice` dSurvey variable equals `3`, then `<radio name="myChoices" append="nChoice" value="1" <` the radio button would be in the `myChoices3` button group.
  `<value > avalue </value>` or `<value var="varname" />` | `value` or `var` | `avalue` is the value of this radio button. Or, if you do not specify a `value` and you do specify a `var`, then the value of `varname` dSurvey variable will be used.
  `<default > logical equation </value>` | `default` | `default` is optional. If specified, the `logical condition` is evaluated. If it evaluates to true, then this radio button is selected as the default. The simplest case is to specify as an attribute: `default="1"` -- which means that this radio is the default! Note if more than one `radio` in a group is the default (more than one have a `default="logical equation"` that are true), only the first one will be the default (and an error message will be written to the status line at the bottom of the page).
  `<submitName>varname </submitName>` | `submitName` | Submit this value to server (when a submit event happens) using this name. If you use an array name (such as `myChoice[ichoice]`, then if the array index (the `ichoice`) is not a number, it will be treated as an dSurvey variable. Thus, if `ichoice` equals 2, then the `submitName` variable will be `myChoice[2]`. Note: you should specify `submitName` for all `<radio>` (whose values, when pressed, you want to save to a server variable).. In fact, you can specify different `submittName` for `<radio>`s in the same group. Shortcut: You can use `<submitName name="varname" />`
  `<submitVar>varname </submitVar>` | `submitVar` | save this value to this dSurvey variable (when a submit event happens) If you use an array name (such as `myChoice[ichoice]`, then if the array index (the `ichoice`) is not a number, it will be treated as an dSurvey variable. Thus, if `ichoice` equals 2, then the `submitVar` will be `myChoice[2]`. Note: you should specify `submitVar` for all `<radio>` (whose values, when pressed, you want to save to a dSurvey variable). In fact, you can specify different `submitVar` for `<radio>`s in the same group. Shortcut: You can use `<submitvar name="varname" />`
  `<label after="1"> html and text </label>` | `label and label_after` | A label for this button. This is simply HTML code that is displayed next to the button, and that when clicked on has the same effect as clicking on the radio button (thus, giving a larger target than the little radio circle). This HTML code may include special attributes and tagnames (such as `<show>`). `after="1"` specifies that the label be after (to the right) of the radio button. If not specified, the label will be to the left (before) the button. Note that if you use the `label` attribute, you will not be able to specify HTML within the label (since you can't put < and > in an attribute).
  `<box style="astyle" class="aclass" > styleChosen </box>` | `box box_class, box_style` and `box_styleChosen` | Place a box around the button, and the label (if specified). When the radio button is hit, the box will be highlighted using the style specified in `styleChosen`.

- If no `styleChosen` is specifed, a default of `border:1px #adacab solid;background-color:#efefef` is used.
- if a different button (in this button set) is hit, the style of a previously hit button will be changed back to its default.
- Thus, the `style="astyle"` (or `box_style`) specifies the default (non-selected). display-style for the box, while the `styleChosen` specifies the button selected display-style.
- You can also use `class="aclass"` (or `box_class`) to specify display-styles that will be used whether the button is selected or not: the `style` (or `styleChosen`) style-attributes being applied after the `class` style-attributes.

  Example::
  `<box style="background-color:#efefef;border:1px brown dotted"
  styleChosen="background-color:lime;border:2px black solid"
  class="myButtonsBasic" />`
  `<confirm> a message </confirm>` `confirm` If specified, one of the buttons in this group must be selected before a `submit event` happens. If not, the `a message` will be displayed, and the information will not be submitted.
  - Only one of the `<radio>` in a group should have `<confirm>` (later `<confirm>`s, in a group, will be ignored).
  - If there are several groups specified on a page that have a `<confirm>` and that are not chosen, only the message for the first failure will be displayed

  #### Special codes

  To customize the `confirm` message, you can insert special word swith the syntax:
  `%varName%`
  The `varname` will be replaced with the value of the `varname` dSurvey variable. This is especially useful when `<radio>` is used within a `<repeat>`.
  Note that `%varname%` must be a seperate word: it must be surrounded by spaces.
  Example, assuming that the `foobar` dSurvey variable has a value of "afternoon" :
  <confirm> You must select an %foobar% train </confirm> would yield a message of You must select an afternoon train
  Suppressing confirmation There may be cases, such as when using a query to force the client to submit his selection, where you do not want to check that a `<radio>` has been chosen. You can suppress confirmation by using a `noConfirm="1"` attribute in the <submit> event.
  `<click>
  equation list
  </click >` Not recommended Equations/etc to execute when the radio box is clicked on. Each radio button has its own click handler. If many radio buttons use the same click handler. consider using the use option to insert a `click` element from `<use>`.
  Equation list can contain alert, confirm, E2_writeStatus, E2_writeAlert, and setting attributes or other element values.
  See working with change & click for the details.
  Example
  <radio > <group name="cSetB" /> <value> 1 </value> <submitName>aChoice </submitName > <label > Chose option 1 </label > <box /> <confirm > You must chose an option </confirm > </radio > <radio > <group name="cSetB" /> <value> 2 </value> <submitName>aChoice </submitName > <label > Chose option 2 </label > <box /> </radio > <!-- two choices, 3 options per choice --> <repeat value="ichoice=1,2" > Choice number <show var="ichoice" />: <ul> <repeat value="ioption=1,3" > <li> <radio > <group name="cSet" append="ichoice" /> <value useVar="1" >ioption </value> <submitName>zChoice[ichoice]> </submitName > <label > Chose option <show var="ioption" /> </label > <box /> <confirm > You must chose an option. </confirm > </radio > </li> </repeat> </ul> </repeat>
  Appendix 4c: Using `<checkbox>`
  `<checkbox>` is used to create a checkbox. You can specify a number of special features. These include:
  - Adding a label to the checkbox
  - Submitting a value if the checkbox is unchecked
  - Putting a box around this label and checkbox, that will be shaded when the checkbox is selected
  Similar to how <value> and <radio> are specified, these features are specified in seperate elements between `<checkbox>` and `</checkbox>`. Or, they can be specified in attributes in the `<checkbox>`.
  Note that `<checkbox>` can contain standard HTML attributes (such as "id", "name", "style", "class", and "accesskey") which will be added to the `<input>` that is created. However, you should not specify a `type=".."` attribute: it will be ignored.

  ID and NAME can be used to find the attribute. In particular, you can use ID or NAME to assign attributes in the `<attributes>` section of the spec file.

  TITLE can be specified as an attribute of `<checkbox>` (or as a `<title>` element in between `<checkbox>` and `</checkbox>`) -- it will be displayed when the mouse is over the checkbox.

  Simple syntax:
  `<checkbox name="varname" value="avalue" />`
  is synonymous with `<input type="checkbox" name="varname" value="avalue" />`.

  However, the real advantage of `checkbox` is its support for a number of useful extensions.
  Syntax:
  <checkbox attributes="..." > <tagname> ... </tagname> // specify fancy features using special tagnames </checkbox>

  Specified using an `<element>` between `<checkbox>` and `</checkbox>` (possibly added via a `use`) | Specified using an `attribute` in `<checkbox>` | Description
  --- | --- | ---
  `<value default="logical condition" > avalue </value>` or `<value default="logical condition" var="varname" />` | `value`, `var`, `default` | `avalue` is the value of this checkbox. Or you can specify a dSurvey variable (whose value will be used) by using the `var` attribute. Note that this only works if the `<value>` is empty. That is, if you use a `<value var="varname" />` syntax. `default` is optional. If specified, the `logical condition` is evaluated. If it evaluates to true, then this checkbox is checked by default. The simplest case is: `default="1"` -- which means that this checkbox is checked by default. ShortCut: specify value using a `value` attribute. For example: `<checkbox value="2" />` Actually, you can use `var` and `value` attributes: if the `varname` evaluates to blank (to '') then the `value` will be used.
  `<novalue > avalue </value>` or `<novalue var="varname" />` | `novalue`, `noValueVar` | `novalue` is the value of this checkbox when it is not checked. This is optional.

- If `novalue` is not specifed, then no variable will be submitted to the server when the checkbox is not checked.
- If `novalue` is specifed, then the value specifed will be submitted to the server when the checkbox is not checked. As with `radio` if `var` is specified, the value of the dSurvey variable (the `varname`) will be submitted.

  `<submitName>varname
  </submitName>` `submitName` Submit this value to server (when submit happens) using this name.
  If you use an array name (such as `myChoice[ichoice]`, then if the array index (the `ichoice`) is not a number, it will be treated as an dSurvey variable. Thus, if `ichoice` equals 2, then the `submitName` variable will be `myChoice[2]`.

  Shortcut: You can use `<submitName name="varname" />`

  `<submitVar>varname
  </submitVar>` `submitVar` save this value to this dSurvey variable (when submit happens)
  If you use an array name (such as `myChoice[ichoice]`, then if the array index (the `ichoice`) is not a number, it will be treated as an dSurvey variable. Thus, if `ichoice` equals 2, then the `submitVar` will be `myChoice[2]`.

  Shortcut: You can use `<submitvar name="varname" />`

  `<label after="1"> html and text
  </label>` `label and label_after` A label for this checkbox. This is simply HTML code that is displayed next to the checkbox, and that when clicked on has the same effect as clicking on the checkbox (thus, giving a larger target than the little checkbox square). This HTML code may include special attributes and tagnames (such as `<show>`).

  `after="1"` specifies that the label be after (to the right) of the checkbox. If not specified, the label will be to the left (before) the checkbox

  Note that if you use the `label` attribute, you will not be able to specify HTML within the label (since you can't put < and > in an attribute).
  `<box style="astyle" class="aclass" > cssStyle </box>` `box box_class and box_style` Place a box around the checkbox and the label (if specified). When the checkbox button is hit, the box will be highlighted using the `cssStyle` specified.
- If no `cssStyle` is specifed, a default of `border:1px #adacab solid;background-color:#efefef` is used.
- if you uncheck the checkbox, its previous default style will be used.
- The default style can be specified using the `style="astyle"` attribute inside of `<box>`.
- Thus, the `style="astyle"` (or `box_style`) specifies the default (non-selected) display-style for the box, while the `cssStyle` specifies the checkbox checked display-style.
- You can also use `class="aclass"` (or `box_class`) to specify display-style (that will be used whether the button is selected or not, with the `style` style-attributes being applied after the `class` style-attributes`style="astyle"`.)

  Shortcut: you can specify the `cssStyle` by using a `styleChosen` attribute. For example:
  `<box style="background-color:#efefef;border:1px brown dotted" styleChosen="background-color:lime;border:2px black solid" />`
  `<click>
  equation list
  </click >` Not recommended Equations/etc to execute when the checkbox is clicked on. Each checkbox button has its own click handler. If many checkboxes use the same click handler. consider using the use option to insert a `click` element from `<use>`.
  Equation list can contain alert, confirm, E2_writeStatus, E2_writeAlert, and setting attributes or other element values.
  See working with change & click for the details.
  Appendix 4d: Using `<doit>`
  Compared to other special tagnames that accept user inputs (such as `<checkbox>`), `<doit>` is designed primarily to process equations, rather than specifying variables to be submitted to the server.

  In particular: `<doit>` does not have a `submitName` or a `submitVar` option. Thus to use `<doit>` for specifying values to submit to the server, you will have to change a session variable and explicitily save it (in a `<submit>` event action).

  #### Using <doit> inside of a <repeat>

  As with other special tagnames, when <doit> is used inside of a <repeat>, the current values of the loop variable will be retained.
  That is, each of the several `<doit>` created by a `<repeat>` will have its own values for the loop variable specified in the `<repeat>`.

  #### Using special tagnames within <doit>

  The contents of a `<doit>` are interpreted as equations -- thus, you do not have to include equations in a `<call>`. However, as an alternative to using attributes within a `<doit>`, several tagnames within a `<doit>` can be specified instead of using attributes.

  tagname | is synonymous with the <doit > attribute ...
  --- | ---
  <link /> | type="link"
  <text value=" a message"/> | text="a message" Note that you can include `<show >` in a `<text>` ... `</text>` (this can not be done when using the `text` attribute).
  <hide /> | hide="1"

  #### Using <content> in a <doit>

  You can use one (or more) `<content>` to specify a block of XHTML code, and where this code should be placed. This XHTML code will be processed for the special tagnames.

  Syntax of <content>
  <content for="idlist" append="1" style="astyle" if="logical Equation" > xhtml code, including special tagnames such as <show> </content >
  where...
  - `for="idlist"` one, or more, html-element IDS (as specified in `id="xx"` attributes). The contents of elements (such as a `<div>`) that contains an `id` contained in `idlist` will be replaced by the xhtml code,..., where this xhtml code,... will first be processed for special tagnames (such as `<show>`).

    Special cases (of ids in `idlist`):
    - `#` : replace the text used in the button, or link, of this `<doit>`.
    - `#after` : Write to the sibling element immediately following the `<doit>`.
      If there is no such sibling element (i.e.; if the `<doit>` is the last element in a `<div>`), an error message is displayed and nothing is changed.
      Hint: Place a `<span />` immediately after the `<doit>`.
    - `#before` : Write to the sibling element immediately preceding the `<doit>`.
      If there is no such sibling element (i.e.; if the `<doit>` is the first element in a `<div>`), an error message is displayed and nothing is changed.
      Hint: Place a `<span />` immediately before the `<doit>`.

  - `if="logical equation"`: If specified, the `logical equation` is evaulated. If it evaluates to `false`, the `content` will be ignored.
  - `append="1"`: If specified, the xhtml content will be appended to the current contents of the elements specified in the `idlist`. If not specified, the contents will replace the current contents.
  - `style="astyle"`: If specified, the style of the elements (specified in `idlist`) will be changed to `astyle`. Note that if `append="1"`, the style is added to the current style. Otherwise, it replaces the current style.

  #### Using <display> in a <doit>

  `<display>`, in a `doit`, allows the client to hide/display an HTML element
  Note: this is slightly deprecated -- consider using the <display> special tagname
  Syntax: `< display target="anid" how="howDisplay" />`
  where ...
  - `target="anid"`: required. the `id` should be the `id` attribute of an existing HTML element (typically a `div` or a `span`).
  - `how="howDisplay"` optional. `howDisplay` can be `none` (to hide the element), `block` (to display as a div), `inline` (to display as a span), or `toggle` (to toggle between `block` and `none`).
    `toggle` is the default.

  #### Useful functions

  Several useful functions allow you to change what the browser is displaying when a `<doit>` is clicked. Note that these are intended for small changes -- for larger changes, use `<content>` instead.

  `displayDiv(adiv,todo)` | Somewhat deprecated: you might want to use `<display>` instead. Toggle display of the adiv element (usually a span or a div) -- where adiv is a string containing the id of the element to be toggled. `todo` is optional. If specified, instead of toggling, the `display` style attribute will be set to `todo`. Recommended values of todo are `"none"` and `"block"` Note that to hide the button (or link) after a click, specify a `hide="1"` attribute in the `<doit>`
  `svy_addStyle('astyle','anid',irep)` | change the `style` attribute of the element with an id of `anid`. `irep` is optional: if set to 1, the style specified in `astyle` will replace the `style` attribute of the `anid` element. Otherwise, it will be added to the `style`. Example: <doit text="Click to make it blue" id="clickMe1" > svy_addStyle('color:blue','showMe1') </doit> <div id="showMe1" > This will be turned blue. </div >
  `svy_addText('text etc.','anid',irep)` | change the `text contents` of the element with an id of `anid`. `irep` is optional: if set to 1, the content's are replaced. Note that only text should be specified -- do not include any HTML elements (for example, do not use `<b>`, or `<show>`, or ...). <doit text="Click to say hello" id="clickMe1" > <hide /> <link /> svy_addText('isHello','Hello. Are you ready?','isHello',1); </doit> <div id="isHello" > A welcome message will be displayed here. </div >

  Appendix 4e: Working with change & click
  The `<change>` and <click> feature of <value>, and the `cliok` feature of checkbox and radio allows you to compute values and execute functions whenever the input field is changed (or clicked).

  First, you can work with the usual dSurvey equation feature, such as using math operators to compute values using session variables. The following lists some features that may be useful:

  - In a `<value>`: you can set the value of this `<value>` by using the following syntax:
    #= an_equation
    Note:
  - that the value you set will be used when saving the `submitVar` and `submitName`.
  - You can not use this `#=x` syntax to change the value of a `radio` button or a `checkbox`
  - To clear the input field of a `<value>` when you first click on it, you can use:
    <click > #='' </click >
  - You can use the current value of a `<value>` or the value of the clicked on `<radio>` or `<checkbox>` `<checkbox>`) by using the following (say, in `an_equation`).
    #value

    Example: To multiply by 10 and remove decimal:

    #=svy_toFixed(#value*10,0)
    Trick: to check the `novalue` value of a checkbox, use `#noValue` (instead of `#value`).

  - You can check the checked status of a `checkbox` or a `radio` by using `#chosen`.
    This returns the value after the click!
    Example:
    <click> tmp=#chosen <if value="tmp eq 1"> alert('The checkbox is now selected ') </if> </click>
    Note that use of `tmp=#chosen` -- since values of attributes can not be used inside of `<if >` statements.

  - To change the style of the input box when you start entering, and after you are done, you can use the `svy_addStyle(astyle,'#id',1)` function.
    Example:
    <change> xx= svy_addStyle(" ",'#id',1) (this will replace the style with a '' (plain vanilla style) </change> <click> (when you click on the box, the style will change xx= svy_addStyle("color:blue;font-size:120%",'#id',0) (characters entered will be displayed with this style </click>
    Note that if you use a 3rd argument of `0`, then the style will be added (rather than replacing the input box's current style).

  - You can set the value of some other element by using the `@elemname=aValue` syntax.
    Example:
    <value> <change> @foo1=svy_dollars(#value) </change> </value> .... You will pay: <span name="foo1" />
    Note that you must identify the target element using a `name` attribute (not an `id` attribute).

  - If `<value>` (or `<radio>` or `<checkbox>`) is used inside of a `<repeat>`, you can refer to indexed elements. For example, the following would input a value, and write it to a cell:
    <repeat value="irow=1,5" > <tr> <repeat value="icol=1,5"> <td> rounded= <span name="myid[irow,icol]"> </span> <value > <change> @myid[irow,icol]=svy_toFixed(#value) </change> </value> </td> </repeat> </tr> </repeat>
  - If you specify a `click` inside of a `<radio>` or a `<checkbox>`, you can suppress a change by "returning" a 0
    <radio group="g1" > <click > <if value="noMoreThis eq 1" > 0 </if > </click > </radio >
    (if the `noMoreThis` session variable is set to 1, then you won't be able to select a radio button that uses the above in a `<click>`).

  end of user's guide