Additional Details on Certain Functions

Additional Details on Certain Functions

POPUP

Returns the HTML for a JavaScript pop-up. The HTML file that contains the text to be shown in the popup (File.htm) is assumed to be in the graphics folder. Or, the HTML file can be elsewhere if referenced with the full http:// path.

The format is:

   PopUp("Link Text", "File.htm", Width, Height)

Example 1:

Assume that you have saved an HTML file containing the help in the study graphics folder. The text below is placed within the question text, such as within Header 1 or Header 2.

   [% PopUp("Click Here for Survey Help", "SurveyHelp.htm", 500, 500) %]

When the survey is run, the above function displays a link that the respondent may click to launch a popup window containing the information in SurveyHelp.htm.

The respondent can retire the popup window and return to the survey by clicking the "X" in the upper-right corner of the popup window.

Example 2:

In this example, we reference an HTML page not in the graphics folder, but somewhere else on your web site. To do this, we include the full URL path to the HTML file.

   [% PopUp("Click Here for Survey Help", "http://www.mysurvey.com/mystudy/help/SurveyHelp.htm", 500, 500) %]

Example 3:

In this example, we replace the "Click Here for Survey Help" text with a graphic.

   [% PopUp("<img src=' " & GraphicsPath() & "help.jpg' alt=' ' border='0'>", "Help.htm", 500, 500) %]

FormatNumber

This function formats numbers with thousands separators, decimal separators, and decimal places. The format is:

FormatNumber (Number, ThousandsSeparator, DecimalSeparator, #DecimalPlaces)

The ThousandsSeparator and DecimalSeparator are enclosed in double-quotes. For example, to make the ThousandsSeparator a comma, you should specify "," as the argument.

Example 1: In the US, the value 7123456 would be formatted as 7,123,456.00. The following script formats this value to US standards:

FormatNumber(7123456, ",", ".", 2)

Example 2: In Germany, the value 7123456 would be formatted as 7.123.456,00. The following script formats this value to German standards:

FormatNumber(7123456, ".", ",", 2)

Example 3: In most cases, you'll be formatting a value contained in a variable (such as a question asked earlier in the survey):

FormatNumber(Q28, ",", ".", 0)

Technical notes: DecimalPlaces can be replaced by a variable that returns a value. Thousands separators and decimal separators can be replaced by a variable that returns text.

Strict Importance

If you use ACA's "Strict" importance function, we do not assume that importance is defined simply by computing the range from the most and least preferred levels within an attribute. We refer to the spread in utility between this respondent's prior best and worst levels (as specified in the attribute a priori order, or by the respondent in the ACARAT questions). If the best minus worst utility is negative, we set the range equal to zero. Strict importance keeps virtually unimportant attributes that potentially have reversals (out-of-order utilities) from getting inflated importance weights. It reduces the effect of random error on importance calculations.

Consider the following part-worth utilities:

$10   1.45
$15   1.50
$20   0.75
$25   0.50

Under standard importance calculations, we take the full spread in utilities for this attribute (1.50 - 0.50 = 1). With Strict importance, we take the spread in importance between the prior best and worst levels (1.45 - 0.50 = 0.95).

As another example, consider the following part-worth utilities:

Has widget "A"   0.20
No widget "A"   0.30

If having widget "A" is expected to be preferred to not having widget "A," based on prior rank-order (or from the respondent's ACARAT question), these utilities suggest a "reversal." The standard importance calculation takes the full range of 0.10 into the computation. Strict importance recognizes this as a reversal, and sets the importance equal to 0 for this attribute. We assume that the reversal is due to this attribute having virtually no importance, with random error overcoming any correct signal from the respondent regarding his/her true preference for levels within this attribute.

Note: this function only applies within the ACA questionnaire. The market simulator (SMRT software) uses the standard definition of attribute importance.

PageTime

PageTime(Startpage, Endpage) returns a value (in milliseconds) between Startpage and Endpage. Endpage is optional. If no Endpage is supplied, PageTime returns the total time spent on Startpage.

You can specify integers as arguments (the page number for the current question is shown at the bottom of the Write Questionnaire dialog when you highlight any question on the list). For example, you may also use: [%PageTime(PageNumber()-3, PageNumber())%] to return the time spent on the previous three pages, without worrying about hardcoding integer values. You might apply that script within a skip pattern to display a warning message if a respondent answered the previous pages too quickly.

If you check the Save Respondent Time per Page setting in the Survey Settings + General Settings tab dialog, the time for each page (in milliseconds) is stored in the data file with variable naming convention sys_pagetime_#, where # is the page number. When you export the data, you can export these variables, and they appear in the export list below any constructed list items. To convert to seconds, divide by 1000.

If the respondent backs up and re-answers a page (using SSI Web's Previous button), new time spent answering that page will be added to the previous time recorded. If respondents use the Back button on the browser to re-answer a page, the total time spent on the re-answered page may not be accounted for correctly.

RadioSelect

This function returns HTML for a radio button, for use within Free Format questions. When Graphical Select buttons are enabled under the Survey Settings, General Format tab, the HTML required for displaying graphical radio buttons is relatively complex. The RadioSelect function returns the HTML necessary for displaying regular or graphical select questions.

The syntax for this instruction is:

RadioSelect(QuestionName, Value)

Where QuestionName is the full QuestionName + Variable extension for a Free Format variable; and Value is the numeric value that is stored when the respondent clicks this particular radio button. Example:

<table>

[%RadioSelect(freeformat_radio, 1)%]

</td>

<td>

ResponseOption_1

</td>

</tr>

[%RadioSelect(freeformat_radio, 2)%]

</td>

<td>

ResponseOption_2

</td>

</tr>

[%RadioSelect(freeformat_radio, 3)%]

</td>

<td>

ResponseOption_3

</td>

</tr>

</table>

In the example above, the Free Format variable is named freeformat_radio. The RadioSelect instruction (highlighted in blue above) is called for each of the three response options (radio buttons), and the appropriate value is saved into the data file for each option. The HTML needed for showing Graphical Radio buttons is supplied when the survey runs on the server.

Notice that we've declared classes "clickable" and "input_cell" within the <tr> and <td> tags. This makes the graphical select feature and the highlight text feature (when respondents mouse-over the response item text) work.

CheckSelect

This function returns HTML for a checkbox, for use within Free Format questions. When Graphical Select buttons are enabled under the Survey Settings, General Format tab, the HTML required for displaying graphical radio buttons and checkboxes is relatively complex. The CheckSelect function makes the Free Format question appear and function like the other Select-type questions in your questionnaire.

The syntax for this instruction is:

CheckSelect(QuestionName, Value)

Where QuestionName is the full QuestionName + Variable extension for a Free Format variable; and Value is the numeric value associated with each item in the checkbox question. Example:

<table>

[%CheckSelect(freeformat_check, 1)%]

</td>

<td>

ResponseOption_1

</td>

</tr>

[%CheckSelect(freeformat_check, 2)%]

</td>

<td>

ResponseOption_2

</td>

</tr>

[%CheckSelect(freeformat_check, 3)%]

</td>

<td>

ResponseOption_3

</td>

</tr>

</table>

In the example above, the Free Format variable is named freeformat_check. The CheckSelect instruction (highlighted in blue above) is called for each of the three response options (check boxes). The CheckSelect instruction will return HTML that declares the variables freeformat_check_1, freeformat_check_2, and freeformat_check_3, and sets all variables equal to 1 if selected, and 0 otherwise. The HTML needed for showing Graphical Checkboxes is supplied (if needed) when the survey runs on the server.

Notice that we've declared classes "clickable" and "input_cell" within the <tr> and <td> tags. This makes the graphical select feature and the highlight text feature (when respondents mouse-over the response item text) work.

DisplayTotal

Returns a grayed out box displaying the total of all questions beginning with FirstQuestionName and ending with LastQuestionName.

The syntax for this instruction is:

DisplayTotal (FirstQuestionName , LastQuestionName, Width)

The FirstQuestionName and LastQuestionName question names need to have the same base question names with a starting number at the end of FirstQuestionName and a last question number at the end of LastQuestionName. DisplayTotal will sum the values for all question names in between.

For example:

[%DisplayTotal (Num1, Num5, 5) %]

will display the total of Num1 + Num2 + Num3 + Num4 + Num5. Notice that all question names must contain the same base name, in this case "Num".

DisplayTotal is useful when using Free Format questions to implement custom constant sum CBC questions. May also be used for non-CBC questions.