Methods of the Form Objects

Overview Methods of Basic Variable Objects

Open text

Date

Numeric

Single

Multi

Open Text List

Numeric List

Ranking

Grid

Geolocation

Element of multi, open text list, numeric list, ranking

Element of grid

Loop

String

.get ()

.set ()

.label ()

.text ()

.instruction ()

.value ()

.valueLabel ()

.getNoResponseValue()

.getType

Array

.domainValues ()

.domainLabels ()

.categories ()

.categoryLabels ()

.values ()

Boolean

.any()

.all()

.none()

.between()

.isNearBy()

Double

.latitude()

.longitude()

1 numeric list item only.

get and set

f(qID).get()
f(qID).set(value)

We have seen these earlier. Used on a question q1,

f("q1").get()

will return the value stored in the database for that object. For an open text question this will be the answer the respondent has typed in the text box, for a single question this will be the code of the answer the respondent has selected.

f("q1").set("1");

With this statement the question q1 can be set to a specific answer. If it is a single question, it is the code value that is set, in this case the answer with code "1". An open text question will be set to the value "1" (string) with this statement.

For multi questions and other question types with several answers (grid, ranking, open text list and numeric list questions), get is not supported. You can use get on individual elements of these question types though (go to Referencing the Elements of a Multi, Ranking, Open Text List, Numeric List or Grid for more information). set can be used to set multi, grid, ranking, open text list and numeric list questions. For multi questions the method will take the codes of the answers that should be set as input as a set, an array or as a dictionary.

f("q1").set(["1","3","4"]);

would set answers with code 1, 3 and 4 in a multi q1 as "selected", and all other answers as "not selected".

It is also possible to set a multi based on the responses to another multi:

f("q2").set(f("q1"));

For grid, ranking, numeric list and open text list, the method will take a dictionary as input, with a collection of key/value pairs (the code of the answer and the value you want to set).

Note: where a compound question has a very large answerlist then attempting to bulk update the entire answerlist may result in poor performance. In such a situation it is recommended to only set the individual elements that require updating, for example: f('multiQid')['answerCode'].set(1);

For date questions, get will return the chosen date formatted as YYYY-MM-DD, or an empty string if no date is set. set can either take a string as parameter (format: YYYY-MM-DD) or a JScript Date object (for example f("q1").set(new Date()) to set current date).

Note: The Date question type is only available when using the Optimized Database format.

label

f(qID).label()

This method is used to access the question title of a question. This method is available on open text, single, multi, numeric, date, ranking, open text list, numeric listand grid questions.

f("q1").label()

will return the title of the question q1.

text

f(qID).text()

This method is used to access the question text of a question. This method is available on open text, single, multi, numeric, date, ranking, open text list, numeric list and grid questions.

f("q1").text()

will return the question text of the question q1.

instruction

f(qID).instruction()

This method is used to access the question instruction of a question. This method is available on open text, single, multi, numeric, date, ranking, open text list, numeric listand grid questions.

f("q1").instruction()

will return the question instruction of the question q1.

value

f(qID).value()

value can be used on single questions to access the code of the answer to the single question (similar to get on a single question).

valueLabel

f(qID).valueLabel()

Use this method on a single question to access the label of the answer to the single question in the current language.

domainValues

f(qID).domainValues()

This will return an array with all codes from the answer list of a single, multi, ranking, open text list, numeric list or grid question, headers excluded.

This method is subject to masking, so if a code mask is used to filter the answer list then this will only return the codes of the answers that are displayed to the respondent.

The method is also subject to randomization. That is, if the answer list is randomized, then the array will be returned randomized.

domainLabels

f(qID).domainLabels()

This method will give an array with all the labels (answer texts) on the question, headers excluded. This is the corresponding answer texts to the codes returned with domainValues. They will be in the current language. The method will give all possible answer texts from the answer list of a single, multi, ranking, open text list, numeric list or grid question. This is also subject to masking.

The method is also subject to randomization. That is, if the answer list is randomized, then the array will be returned randomized.

categories

f(qID).categories()

categories will return an array with the codes of the items that have been answered on a multi, ranking, open text list, numeric list or grid question. For a multi question, this will be the codes of the answers that have been selected, for a grid this will be the codes of the answers that have an answer. Usually a grid is required, so categories will be equal to domainValues for a grid. But if the grid is not required, they may differ.

Note: If a code mask is used to filter the answer list, then this will only return the codes of those answers that are displayed to the respondent. The f() will not return the results of a combination of answers selected by the respondent and answers added by script.

Copying a Multi to do Response Piping with "Other, specify"

In the example in The Conditional Expression Ternary Operator, we saw how you could pipe in the answer in the text box of an "other, specify" option on a single question. However, you cannot use the same approach on a multi question because there "other, specify" can be answered in combination with any of the other alternatives.

A way of solving this for a multi question is to copy the answer of the multi question into another hidden multi question with the same answer list, except that for "other, specify" you pipe in the response from the text box into the answer list instead.

So if you have a multi question musicals with an "other, specify" alternative with code 98 and the "Other" property set to yes, you can set up a second multi question musicals_hidden with the "hidden" property, where the answer from the "other, specify" text box is piped in with the syntax

^f("musicals_98_other")^

Figure 1 - Setting up a second multi question

Then you need a script node to copy the response from musicals into musicals_hidden. Copying answers from one question to another hidden question can also be something you need to do for example to have different, shorter answer texts in response piping in a later question, or to have different texts for reporting.

f("musicals_hidden").set(f("musicals").categories());

For this script to work, musicals and musicals_hidden need to be of the same question type and have exactly the same answer lists (same number of items and same codes).

The script is to be placed after the musicals question:

In the info node you may now refer to the musicals_hidden question in your response piping:

You have seen these musicals:

^f("musicals_hidden")^

If the respondent for example answers like this:

Figure 2 - Respondent providing an answer

the result of the piping will be:

Figure 3 - Result of the piping

categoryLabels

f(qID).categoryLabels()

This method will return an array with the labels of the items that have been answered on a multi, ranking, open text list, numeric listor grid question in the current language, i.e. the texts from the answer list corresponding to the codes returned from categories.

values

f(qID).values()

values will return an array with the answers stored in the database for a grid, multi, ranking, open text list or numeric list question.

For a grid question this will be the codes of the answers to the questions (from the scale).
For ranking, open text list or numeric list questions it will be the numbers or texts answered for each item in the answer list.
For a multi question this will be 1 (selected) and 0 (not selected).

Note: If the multi question is hidden, then the return will be 1 (selected) and null/blank (not selected).

.getNoResponseValue()

f(qID).getNoResponseValue()

This method returns the value stored for the Don't Know or Refused question property supported on Open Text, Numeric, Open Text List, Numeric List type questions.

Values returned are:

dk: respondent chose the Don't Know option.
ref: respondent chose the Refused option.
null: neither Don't Know nor Refused options were chosen; or the property was not enabled in the question.

Examples of use in conditional expressions:

f('qid').getNoResponseValue() == 'dk'

f('qid').getNoResponseValue() == 'ref'

f('qid').getNoResponseValue() == 'null'

getType

f(qID).getType()

getType will return the type of the question. The result returned for the various question types are:

Open text question - OPEN
Numeric question - NUMERIC
Single question - CODED
Multi, ranking, open text list, numeric list and grid questions - COMPOUND
Other specify - OPEN
3D-grid and multi grid - 3DGRID
Date - DATE
Image upload - PHOTO
Audio upload - AUDIO_CAPTURE
Video upload - VIDEO_CAPTURE
Geolocation - GEO
Boolean (property on single question) - BOOL
A question referring to an external answer list in database designer - EXTERNAL

The getType method can be used to determine the type of question in a general purpose script for example for validation.

Note: You cannot set the value for an Image Upload, Audio or Video Capture question.

GetAdditionalColumnValue

This is a survey engine scripting method used to retrieve data from an additional column or columns associated with a specific table inside of a table lookup list.

f('qid').GetAdditionalColumnValue(code, additionalColumnName)

where:

code is the id to query from the lookup table.
additionalColumnName is the name of the additional column from which data is returned.

This will return the data in the specified additional column name in the table lookup for the question “qid” for the code supplied, in the same language the interview is being completed in.

In this example where there is a single question “sales_rep” based on a database lookup “car_rep”:

Figure 4 - question "sales_rep" based on database lookup "car_rep"

The “salesRepDetails” info node contains the following piping of the additional columns “office” and “joined_year”:

Figure 5 - "salesRepDeatils" info node

This is achieved using the following syntax:

Your sales representative, ^f('sales_rep')^, is based in
^f('sales_rep').GetAdditionalColumnValue(f('sales_rep').get(),"office")^, and
joined in
^f('sales_rep').GetAdditionalColumnValue(f('sales_rep').get(),"joined_year")^.

Note: In most cases the code value supplied in the method will refer to the f(‘qid’).get() for the question that the lookup is based on.

You can perform a test to check whether the code exists in the table used as qid’s answerlist. If the code doesn't exist in the table lookup then the method will return "undefined".

To test if the code exists in the table lookup, and display an error message if not, add the following:

if(f('qid').GetAdditionalColumnValue(code,additionalColumnName)==undefined)
{
 RaiseError();
 SetQuestionErrorMessage(LangIDs.en,”Error – that code doesn’t exist in the lookup table”);
}

Note: The GetDBColumnValue function is described here (go to GetDBColumnValue for more information).

any

f(qID).any(code1,…,coden)

any will return true if any of the codes listed is answered on a single or multi question, or if any of the items for these codes have a response on a grid, multi, ranking, open text list or numeric list question, or false if none of these items has a response. The method is for example useful in conditions.

all

f(qID).all(code1,…,coden)

all will return true if all of the codes listed is answered on a multi question, or if all of the items for these codes has a response on a grid, multi, ranking, open text list or numeric list question, or false if none of these items has a response. The method is for example useful in conditions.

none

f(qID).none(code1,…,coden)

none will return true if none of the codes listed is answered on a single or multi question, or if none of the items for these codes has a response on a grid, multi, ranking, open text list or numeric list question, or false if either of these items has a response. The method is for example useful in conditions.

between

f(qID).between(from, to)

between will return true if the answer to a numeric question or an item of a numeric list question is between the from value and the to value, or false if not. This means the value answered is higher than or equal to the from value and lower than or equal to the to value. The method is for example useful in conditions.

isNearBy

f(qID).isNearBy(latitude, longitude, distance)

isNearBy can be used on Geolocation questions, and will return true if the position recorded in the question is within a given distance in meters from the position defined by the latitude and longitude. Latitude, longitude and distance are all numeric (double).

latitude and longitude

f(qID).latitude()f(qID).longitude()

Latitude and longitude can be used on Geolocation questions, and will return the latitude and longitude of the position recorded in the question.

f(qID).setNoResponseValue(‘’)

Forsta Scripting Support

Articles in this section