Script Objects

For advanced routing, on-the-fly recoding, redirects, calculations on answers to questions or other programming efforts, you can insert script-objects that will run JScript-code when executed. When using script objects, care must be taken to create codes that will run without errors. JScript is an interpreted programming language, which means that the code will only be checked at run-time. You should always perform thorough testing of Surveys that include script objects.

Example:

You can use a script object to for example change the status for the respondents before they have actually finished the interview. You may have some pages at the end of your interview after the final "data question", and it would then be possible for a respondent to end the interview by closing their browser after having answered all your questions but before the final page is reached. This could result in an "incomplete" status for the respondent even though you have got a full set of data from them. To avoid this you can include a SetStatus script in the survey immediately after the last question but before the additional pages. The script required in this case would be:

SetStatus('complete');

As the respondents pass the script node their status will then be set to Complete even if they end the interview before reaching the last page.

Note: For Optimized database surveys, if a survey scripter attempts to set an unknown code on a single, grid or 3D-grid, the value is ignored (not set), and a warning email is sent to the survey owner. The respondent will not see any errors. In a similar fashion, if a scripter attempts to set a value that is longer than the field width, the value is truncated and an warning email is sent to the survey owner. Again, the respondent will not see any errors.

Predefined Scripts

In a Script object and the Masking tabs for many of the question types, you have the option of using predefined scripts. These are scripts that have been developed and tested by Forsta, and are intended to simplify scripting operations for the users. In the Script object, the predefined scripts available can be used as they are, or you can convert them to script code and use them as the start point for more complicated scripts. In the Masking tabs, the predefined scripts are used "as-is".

1. In the script object, or on the Masking tab when available, click the down-arrow beside the Select Predefined Script field, and select the script you wish to use - .

Figure 1 - Selecting a predefined script for a Script object

Note: The list of predefined scripts available in the Script nodes and Masking tabs will be expanded as commonly-used scripts are developed and tested. Note that some scripts may not be available in both places.

1. Fill in the input fields as required.
2. Click Save to save your changes.

Click Append to Script Code if you want to use the selected predefined script as the basis of a more in-depth script that you wish to develop yourself.

In the figure below - - the URL Redirection predefined script was selected on a Script object, a URL was entered, and the Append... button was clicked. This has added the script code to the scripting field, allowing you to edit the code as required.

Figure 2 - Appending the script ready for further editing

Note: If you wish to use the predefined script "as-is", then you do not need to click the Append... button.

Random Category Selection Script

This predefined script is available in Script objects. It selects a specified number of options, at random, from the overall list of answer options included in the specified question. This can be used for example if you have a multi question with 10 answer options, and you want to present the respondents with 5 of those options selected randomly from the list, such that they can perhaps choose 3 preferred items from the 5 that are selected - .

In the figure, when the respondent arrives at the Cars Tested question, he/she will be presented with 5 answer options that have been selected from the list of options that are available in the question.

Figure 3 - Using the Random Category Selection predefined script

Click Append to script code if you want to use the selected predefined script as the basis of a more in-depth script that you wish to develop yourself.

URL Redirection

This predefined script is available in Script objects and is used to redirect the respondents to a different URL - . This is similar to the End Link property (go to URL Setup for more information), however this predefined script can be expanded to send different respondents to different URLs.

Type the desired URL into the field using the format specified. Leave the "Close survey..." box checked if you wish to prevent the respondent from returning to the survey after he/she has been redirected.

Figure 4 - Using the URL Redirection predefined script

Note: This predefined script will also set the current date/time in interview_end and the respondent’s status to ‘complete’. So the settings in the figure above are equivalent to:
SetStatus('complete')
SetInterviewEnd()
Redirect('http://www.Forsta.com')

Click Append to script code if you want to use the selected predefined script as the basis of a more in-depth script that you wish to develop yourself.

Include and Exclude

The Include and Exclude predefined script is available in the Masking tab for Single, Multi, Ranking, Grid, Numeric List and Open Text List questions - .

A mask will be applied to this question, whereby when you type question IDs or drag questions into the two fields, the script either includes or excludes (selected in the drop-down) all categories selected for the specified questions.

1. Drag the questions from the Survey Tree toolbox and drop them into the fields, or type the question IDs into the fields.
2. For each field, click the down-arrow beside the drop-down box and select whether you wish to include or exclude the categories associated with the question.
3. Save the changes.

The Code Mask area when the Include and Exclude predefined script is selected

Only one question can be dragged or typed into each field.

Mask on Question

The Mask on Question predefined script is available in the Masking tab for Single, Multi, Ranking, Grid, Numeric List and Open Text List questions - .

A mask will be applied to this question whereby, when you type a question ID or drag another question into the Filter by... field, the script either includes the selected categories in the question that is added, or excludes those categories from the question (as selected in the drop-down box).

1. Drag the question from the Survey Tree toolbox and drop it into the Filter by... field, , or type the question ID into the field.
2. Click the down-arrow beside the Include/Exclude field and select as appropriate.
3. Save the changes.

The Code Mask area when the Mask on Question predefined script is selected

Only one question can be dragged or typed into the field.

Assign Request Values

The Assign Request Values predefined script is available in Script nodes - . When you use this script, you need to supply a comma-separated list of question IDs. These IDs will have their values pulled from the URL querystring and assigned to a variable with the same name. The question IDs will not be case-sensitive.

Figure 5 - Using the Assign Request Values predefined script

Click Append to script code if you want to use the selected predefined script as the basis of a more in-depth script that you wish to develop yourself.

Include or Exclude With Codes

The Include or Exclude With Codes predefined script is available in the Masking tab for Single, Multi, Ranking, Grid, Numeric List and Open Text List questions - .

Drag the questions from the Survey tree or type in the question IDs that are to act as masks for this question. Use the dropdown to control whether the selected categories are to be displayed (Include) or not displayed (Exclude) . If required, enter a comma-separated list of codes to force Include and/or Exclude.

The format is: [Include/Exclude] selected categories from [question A] but force category(ies) [x,y,z] to be included and [a,b,c] to be excluded.

The Code Mask area when the Include or Exclude With Codes predefined script is selected