Creating dSurvey SPEC files || dSurvey extensions: main features

## XHTML extensions for dSurvey: secondary features

This document describes secondary features of dSurvey's XHTML extensions. These features either replicate (often not as well) capabilities documented in the main features documentation. Or they are features that are infrequently used. Sometimes, they are features that are a little bit confusing! Thus, these features are mostly deprecated. They are still supported, but their use is not recommended.

Processing the dSurvey XHTML attributes. Note that features these attributes enable can often be specified using the special tagnames.

- SETVALUE to set the value of elements
- basic features:
- Using several elements
- Using several elements: specifying processing order
- Using logical equations
- Useful Features
- KEEP to display, or not display, elements
- INFOLINKS to add help messages
- KEYINC, CHECKBOUNDS, CONFIRM event handlers
- Setting the focus

Using setValue: to set an HTML element's value, and more!
This feature (using a class of `set`) is mostly deprecated.
We recommend using the <set> special tagname
The `setValue` special attribute allow you to dynamically set the value of an element. Using it requires a few simple steps:

Include `set` as one of the element's classes. Include a `setValue` attribute Specify a session variable as the `attribute value` of the `setValue` attribute. | Example: `<Input type="text" class="set" setValue="costLow" />` If the current value of the `costLow` session variable was 25.5, this would yield:

However, you can do a lot more!

Let's start with some basic features:

Setting a session variable. Calling a function. The value returned by this function can be used as the elements value, or as the value of a session variable. Multiple actions: setting one or more variable, and calling one or more functions. | Setting a session variable value Instead of setting the element's value you can set the value of a session variable. To do this, use a syntax of:`setValue="varname=avalue"` . For example: `<div class="set" setValue="v11=11" />` would set the `v11` session variable to be equal to `11`. Note that the value of the element will not be changed (in the above example, the empty value will stay empty). Calling a function The basic syntax for calling a function can take two forms: `setValue="funcName(arg1,...,argn) "`. The value returned by the `funcName` function is used as the value of the element. `setValue="aVar=funcName(arg1,...,argn) "`. The value returned by the `funcName` function is used as the value of the element `avar` session variable. where... `funcname` can be any valid javascript function (case sensitive). You might find that some of the built-in functions are useful. The `argn` arguments (you can have up to 8) are treated as strings. Thus, it is up to the function to properly interpret the argument (say, to look up a session variable, given its name). You can review the order that equations are processed. Multiple actions You can specify multiple actions: such as setting several variables, calling functions, and setting the element's value. This is done by seperating each action with a semi-colon. Example: `setValue="tmp1=100 ; aVar1=func1(tmp1) ; avar2=func2(avar1,myPrice) ; avar2 "` Note that the final `avar2`, since it is not preceded by a `varname=`, means that the element's value will be set to the value of the `avar2` session variable.

Using several elements
You can do a lot with the above extensions, but things can get quite cluttered. So, it is often convenient to use several elements, rather then just one. Elements are processed in order of appearance, so that session variables set in earlier elements can be used by later elements.

Example: <div class="set" setValue="v11=11" /> <div class="set" setValue="v12=1200" /> <div class="set" setValue="v21=2100" /> <div class="set" setValue="v22=funcZ(v21,v11)" /> <div class="set" setValue="v3=funcX(v22,v12)" /> The variables will be set in the following order: `v11, v12, v21, v22, v3`. Note that `funcX` and `funcZ` use the session variables set in elements processed earlier (such as `v22` and `v12`).

Using several elements: specifying processing order
Although it might violate proper programming principles, there may be times when you want to specify an order of processing that does not depend on order of appearance. You can to this by including a `order="n"` attribute.
Elements with a `order="1"` will be processed first,
then elements with `order="2"`,
etc etc etc.
Notes:

- elements without a `order="n"` are processed first (they are assumed to have an `order="1"`).
- elements with the same value of `order` will be processed in order of appearance

Example: that yields the same order as the above example ...
<div class="set" setValue="v11=11" /> <div class="set" order="3" setValue="v3=funcX(v22,v12)" /> <div class="set" order="2" setValue="v21=2100" /> <div class="set" order="2" setValue="v22=funcZ(v21,v11)" /> <div class="set" order="1" setValue="v12=1200" />
Using logical equations
Although functions can do a lot, they might be cumbersome to use. Instead, logical equations can be used to control an element's value. This is done by using `if`, `then`, and `else`.

`if="logical equation"`: specify logical conditions `then=" stufff "` : process stuff if the logical conditions are true `else=" stufff "` : process stuff if the logical conditions are false Basically:: `then` and `else` are synonymous with `setValue` -- except which one is used depends on the `if` | #### Details... `logical equation` should have be an equation that contains the logical operators:`== != GT LT GE LE NE EQ AND OR XOR`, where the 2-3 letter codes must have spaces before and after. Notes: To check if a session variable that has been defined is used, use the `EXIST` function Note the use of `GE` etc. That's because it's difficult to use < and > inside of an element! `else` is optional : when `if` evaluates to `false`, and no `else` is specified, do nothing (do not change the element's value). Hiding an element: when `if` evaluates to `true` and `then="HIDE"`, the element is not displayed (its visibility is set to `hidden`). Or, if `if` evaluates to `false` and `else="HIDE"`, the element is not displayed. Note that you can also use the KEEP class to hide elements. For more complex logic, it may be easier to specify it using <attributes>. If you specify an `if` and a `setValue` in the same element, the `setValue` is ignored.
Examples: <div class="set" setValue="v11=11" /> .... <div class="set" if="v11 == 12" then="'Current value is 12'"> Current value of v11 is not 12, so this element isn't changed (since there is no else="...") </div> <div class="set" if="v11 == 12" then="'Current value is 12'" else="not12=1" > Current value of v11 is not 12, and not12 is now equal to 1 </div> <div class="set" if="v11 == 13" then="'Current value is 13'" else="'Current value is not 13'" /> <div class="set" if="dispMe lt 1" then="HIDE" > Hello! But if dispMe is 0, this will be invisible. </div>

Useful Features
One of the strengths of the dSurvey XHTML extensions is the ease of dynamically changing content. This dynamicism allows you to ...

1. Setting the values of XHTML elements when a `group` is loaded (that is, setting what is displayed on the screen when a new group is started). This is discussed in the Setting values portion of this document.
2. Changing the values of XHTML elements in response to user actions.
3. Adding help links to XHTML elements

Discarding blocks of XHTML elements
This feature (using a class of `keep`) is mostly deprecated.
We recommend using the <if> special tagname
To keep, or discard, elements, specify an enclosing element (such as a `div`) that incorporates the elements you wish to discard. This element must:

- have a `tagname` of `div, span, li, tr,` or `td`
- have `class` of `KEEP`
- have a `if="logical condition` attribute.

Details ...

- `if = logical equation.`
  If this logical equation evaluates to true, the element is displayed. Otherwise, it is removed (and not displayed).
  This is an alternative to using then="hide" in a `setValue`. However, it is a bit more complete -- rather then setting `visibility` to hidden, it removes the XHTML element.
- KEEP can only be used in `div, tr, td,` and `span` XHTML elements.
- You can nest elements that have KEEP -- if an outer element is removed, the inner elements are also removed regardless of the values of their logical equations.

- Using `KEEP` in `<tr>` elements is a simpler, though less powerful, way to create dynamic tables.

Example...
some stuff... <div class="KEEP" if="yourIncome gt 100000" > various stuff ... </div> more some stuff...
Adding event handlers to XHTML elements
These features are mostly deprecated.
We recommend using the <value> special tagname
To use the tools described in the next table, one must include special class values in elements subject to change (as the result of user actions). In addition, attributes that contain control parameters must be set.

You can use the `setValue` attribute, or use `<set>`, to define these control parameters. In some cases, you must use `<set>`.

Action | class | Attributes (attributes used by this action)
--- | --- | ---
Using arrow keys to increment numeric values in a text-box | KEYINC | `value_Default`: The value to use when an ESC key is hit. When ESC is hit a 2nd time, a blank will be displayed `value_Fmt`: The number of digits to the right of a decimal point. Thus, if the value is 123.4567 and `value_Fmt=2`, then `123.45` will be displayed.
Check bounds of a numeric string, and force it not to exceed the bounds. | CHECKBOUNDS | `value_Max`: maximum allowed value. This can be a number, a session variable, an @element_value, or a #attribute_value. If the entered value is > `value_max`, it will be set to `value_max`. `value_Min`: minimum allowed value. This can be a number, a session variable, an @element_value, or a #attribute_value. If the entered value is < `value_min`, it will be set to `value_min`. `value_Fmt`: The number of digits to the right of a decimal point. Thus, if the value is 123.4567 and `value_Fmt=2`, then `123.45` will be displayed. If the entered value is greater than `value_max`, it will be set to `value_max`.
Check a numeric value to see if it is suspiciously large or small. If it is, ask if user really want to enter that value. | CONFIRM | `confirm_Name`: short name for this variable (used when displaying confirmation box). `_Name`: short name for this variable (used when displaying confirmation box). This is only used when `confirm_Name` is not specified. `confirm_Max`: High value -- if entered value is > `confirm_Max` a are you sure? confirmation box is displayed. `confirm_Min`: Low value -- if entered value is < `confirm_Min` a are you sure? confirmation box is displayed. `confirm_Allowed`:Used when a limited set of 1-word string values are permissible. Should be a space delimited string listing all "one-word" values that are permissible. `value_Fmt`: -- see above -- `if _Empty`: if a blank value is entered, insert the value of `ifEMpty`. Note that this value will be treated as an session variable. Or, you can use a number, a 'quoted string', a @elementValue, or a #attribute_value.
Specify equations/functions/etc to process when a value is changed. | CHANGE | `changeCall="equation list "`: the `equation list` is a semi-colon delimited list of equations and functions (use the same syntax as setValue). For more complex actions (say, that use `if` and `do`), specify a `changeCall` attribute in attributes (where a one-equation-per line syntax is used). If both are specified (a `changeCall` attribute in the XHTML element, and a `changeCall` attributes in the `attributes` section), the `attributes` version is used. In either case, list-of-equations can be used to set session variables, the value of an XHTML element, or the value of an attribute of the current XHTML element. Example (for a `changeCall` in `attributes`): <changeCall > @earning= svy_toFixed(#value - @prodCost1,2) <if value="@earning lt 0" > alert(' Negative? ') </if> </changeCall > Notes: You should not use `#attribute_values` in `if` statements. A work around is to set a temporary variable (equal to an `#attribute`) outside of the `if`, and then use this temporary variable in the `if`.

Adding help links to XHTML elements
This feature (using a class of `infolinks`) is mostly deprecated.
We recommend using the <info> special tagname
The INFOLINKS class is used to display help messages.
That is: INFOLINKS 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.

Display a help message. The text associated with an element that has an `INFOLINKS` class will be formatted to look like a link. When this "link" is clicked, a message box opens up and displays a help message. Example: <div class="INFOLINKS" infoName="Tip1" title="Various tips and tricks" helpWord="Tip Number 1 " noHelpBox="0" > Item1 Tips </div> (this assumes that a module named `Help_Tip1` is available). Note that Item1 Tips will be a clickable link, displayed using an underlined blue font. | INFOLINKS | `infoName`: The name of the module containing the help message. `name`: Used only if `infoName` is not specified. A `Help_` is prepended before the `name` value, and used as the module name (if `infoName` is used, nothing will be prepended). `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 :` You can change the `Help_` to a different prefix by setting a `_helpModule_prefix` session variable (say, in the `<init>` section of your specification file). There are several CSS definitions you can change (in `svyLibE2.css`) that allow you to customize display: `styleInfoLink`, `styleInfoLink_header` and `styleInfoLink_body`

Notes:

- The attributes used by these event handlers (such as `confirm_Max`) are evaluated when the event (say, a text box is changed) occurs.
  Thus, if you use a session variable name as an attribute, its value will be determined when the event happens, and not when the group is loaded.

Setting the focus
The FOCUS class is used to set the focus of the display.

To use `focus`, just add a `class="FOCUS"` (or add `FOCUS` to an existing class) to any `DIV`, `SPAN`, or `INPUT` element. This will override a focus that is set using a `<focus>` in a SPEC file, and may override a `focus="1"` set in a `<button .. >` event.