GetSurveyChannel
GetSurveyChannel()GetSurveyChannel is used to show which channel the survey is being executed on. A String value indicates the channel type as listed below:
String returned |
Description |
Capi |
CAPI interview |
| Cati | CATI interview |
Cawi |
Web interview |
| RandomDataGeneration | Response is generated using Random Data Generator |
| SDK | Mobile App SDK survey |
SelfCompletionSurvey |
Self completion interview (via AskMe app) |
This function can for example be used to store the channel in a hidden single question channel by setting it in a script node:
f("channel").set(GetSurveyChannel())Another example is to use it inside a condition to ask certain questions only to web respondents:
Figure 1 - Using GetSurvey Channel in a condition
A third example is to use it to display certain texts only when the interview is performed by an interviewer (CAPI or CATI):
Figure 2 - Using GetSurveyChannel toddisplay certain texts only when the interview is performed by an interviewer (CAPI or CATI)
IsInProductionMode
IsInProductionMode()IsInProductionMode() can be used to distinguish between running surveys in production mode or in quick test/external quick test/test mode. It will return one of the following values:
| true | Production mode |
| false | Quick Test/External Quick Test/Test mode |
GetRenderingMode
GetRenderingMode()GetRenderingMode() can be used to determine whether desktop rendering, one of the mobile rendering modes (touch or generic), is currently active in the survey. This function can for example be used in a condition if you would like certain questions only to be presented in the desktop version of the survey. If responsive rendering is activated, GetRenderingMode will return "responsive".
To get the mobile rendering modes (touch and generic), these modes must be active on the survey.
| desktop | Desktop rendering (PC/Mac/tablet) |
| responsive | Responsive rendering mode |
| touch | iPhone/iPod touch/Android phones |
| generic | All other mobile phones |
If you for example want to provide some questions only to users accessing a survey through the desktop rendering, you can use the following expression in a condition, and then place those questions inside the Then branch:
GetRenderingMode() == "desktop"
GetContentType
GetContentType()GetContentType() can be used to distinguish between surveys run as regular Web surveys or through a Flex extension using the Survey Front End extension point, such as iPhone, Android and SMS surveys. It will return one of the following values:
| Html | Run as a regular web survey |
| Json | Run using the Flex Survey Front End extension point using Json |
| Xml | Run using the Flex Survey Front End extension point using Xml |
AdvancedWIFeaturesEnabled
AdvancedWIFeaturesEnabled()AdvancedWIFeaturesEnabled() is used to determine whether the respondent’s browser supports Advanced WI Features that require client side scripts, such as sliders, drag-n-drop ranking, images instead of radio-buttons/check-boxes etc. It will return true if the respondent’s browser supports the advanced WI features, or false if not. It can for example be used to display a different instruction text depending on whether or not respondents will have a question displayed with the advanced WI interface.
This function is optimistic with regards to checking whether JavaScript is turned on or off in the browser. In other words it will return true unless it is determined that JavaScript is turned off.
Note: This state can only be determined once the respondent has opened the first page of the survey. This function must therefore be executed after the first page of the survey.
Displaying different instruction if Advanced WI feature is being used
If you have a question using the drag-n-drop ranking feature, you may present two different instruction to respondents: One for respondents that have a browser supporting the drag-n-drop interface, and another one to respondents that do not have a browser supporting these. The latter will then get the question with ordinary input boxes where they can rank with numbers.
This can be done by using a ternary conditional expression with the AdvancedWIFeaturesEnabled function in the instruction text field of the questionnaire.
^AdvancedWIFeaturesEnabled() ? "Please rank the cars by dragging them over to the right hand side, the first indicating the one your are most likely to buy and so on" : "Please rank the cars by entering numbers in the text boxes. 1 for the car your are most likely to buy, 2 for the second most likely and so on"^
DynamicQuestionsEnabled
DynamicQuestionsEnabled()DynamicQuestionsEnabled() is used to determine whether the respondent’s browser supports AJAX so that the “Dynamic Questions” functionality can be used (go to Dynamic Questions for more information). It will return true if the respondent’s browser supports AJAX, or false if not.It can for example be used for screening respondents from a survey that have extensive usage of .this, or in a condition to provide an alternative path for respondents, if they have a browser that does not support it. Unlike “Advanced WI Features”, no fallback (i.e. alternative interface) exists for this functionality.
IsDynamicQuestionCallback
IsDynamicQuestionCallback()IsDynamicQuestionCallback is used to determine whether the code is currently executed during a Dynamic Question Callback, i.e. an Ajax update of one or more Dynamic Questions. This will be true if used within a question that has a trigger, when one or more of the trigger questions is updated.
IsInlineSurveyCallback
IsInlineSurveyCallback()IsInlineSurveyCallback is used to determine whether the survey is currently run as an inline survey.
Figure 3 - Using IsInlineSurveyCallBack to determine whether the survey is currently run as an inline survey
For "regular" surveys, the response record is created when the respondent opens the first page of the survey (this is the default). However for inline surveys, the response record is created when the respondent submits the first page of the survey. This is done to reduce the amount of empty data records, since an inline survey may be placed within high volume sites where only a small percentage of the visitors will submit a response.
It is therefore not possible to use the .set() method in a script within the first page to store responses when the survey is running inline, because the data cannot be stored in the database since the database record does not yet exist. Such scripts can only be run from the second page onwards.
If you need to retrieve values from the query string using Request(go to Request for more information) and store in the database, you will have to do this on the second page. In inline mode the query string is preserved when moving from the first to the second page.
If the survey is accessed both in inline mode and as a regular survey link, you do have to treat these modes differently, and the IsInlineSurveyCallback function can be used for this. Let's say you send in a value site=1. At the start of the survey you can add this script to fetch the value when the regular survey link is opened:
JScript example:
if(Request("site")!=null &&!IsInlineSurveyCallback())
{
f("site").set(Request("site"));
}
Before the second page, you can insert the following script to fetch the value when the survey is inline:
if(Request("site")!=null &&IsInlineSurveyCallback())
{
f("site").set(Request("site"));
}
JavaScript example:
if(Request.QueryString.item("site")!=null &&!IsInlineSurveyCallback())
{
f("site").set(Request.QueryString.item("site"));
}
Before the second page, you can insert the following script to fetch the value when the survey is inline:
if(Request.QueryString.item("site")!=null &&IsInlineSurveyCallback())
{
f("site").set(Request.QueryString.item("site"));
}
CurrentForm
CurrentForm()CurrentForm is used in validation code, masking and in response piping in a question's text fields (or in functions called from validation code, masking and response piping) and returns the question ID (string) of the current question. Used inside the validation code field of one of the questions inside a 3D grid, it will give the question id of that question instead of the id of the 3D grid itself.
You can use this to write generic code that can be reused without having to change the question ID.
Note: For questions within a 3D-grid, CurrentForm works only in validation code scripts. For piping or other scripts within a 3D-grid the evaluation depends on the execution context, so CurrentForm will not function correctly.
GetRespondentUrl
JScript example:
GetRespondentUrl() GetRespondentUrl(string qid) GetRespondentUrl(string qid, params string[] loopQual) GetRespondentUrl(string id, bool isCallBlock) GetRespondentUrl(string id, bool isCallBlock, string parameters) GetRespondentUrl(string id, bool isCallBlock, string parameters, params string[]loopQual)
When using JavaScript survey engine, there is only one signature for this function.
JavaScript example:
When using JavaScript survey engine, there is only one signature for this function.
GetRespondentUrl(string questionId, bool isCallBlock, string userParameter, params string[] loopiters)
Where:
qid is a question id.
id is either a question id or a callbock id.
isCallBlock denotes whether the id is a question id or a callblock id.
parameters is a string to be passed into the survey in the url; the string can contain one or more parameters; where more than one parameter is being used a semi-colon should be used as a separator.
loopQual is only applicable when the question id exists within one or more loops and the url is being used to direct the respondent to a particular iteration.
GetRespondentUrl returns a URL that will allow the current interview to be entered at a specific point.
All of the parameters are optional. If they are not used the URL will, depending on the Survey Settings, take the user either to the beginning of the interview or to the last question where they left off. But when they are used, they can provide the following capabilities:
- The respondent can be directed to the page of a particular question, and, if the question is inside one or more loops, a particular loop iteration or iterations. The interview will then continue from that point.
- The respondent can be directed to a particular callblock which, upon completion of the callblock, will finish the interview.
- The function can securely pass a text value or several text values into the start of the interview, that will then be accessible via the
UserParametersfunction.
GetRespondentUrl can be used for example to send an email to the respondent to allow him/her to re-access the survey, or it can be presented inside the survey so that the respondent can copy it to return to the survey later.
To follow are some examples of different combinations of the optional parameters, and cases where they may be used.
In this example,
GetRespondentUrl("q9")will give a link that when opened, will open the survey for the current respondent on the page with q9, and then continue through the interview. This could also be written as:
GetRespondentUrl("q9", false)which will have the exact same effect.
In this example,
Figure 4 - Using GetrespondentUrl
JScript example:
GetRespondentUrl("q7","3","2")
JavaScript example:
GetRespondentUrl("q7",false,UserParameters,["3","2"]);
will give a link that when opened, will open the survey for the current respondent on the page with q7 for the iteration with code "3" of l2 and the iteration with code "2" of l1.
In this example,
Figure 5 - Using GetrespondentUrl 2
GetRespondentUrl("alert", true)will give a link that when opened, will open the survey for the current respondent at the start of the call block named “alert”. When the respondent finishes the callblock, after submitting the i40 info node, the interview will finish.
In this example,
GetRespondentUrl("q12", false, "alert=true")will give a link that when opened, will open the survey for the current respondent on the page with q12, passing the encrypted parameter named alert with a value of “true” (see the UserParameters function for details regarding accessing the parameter).
In this example,
GetRespondentUrl("", false, "alert=true;state=red")will give a link that when opened, will start from the beginning of the survey, passing the encrypted parameters named “alert” and “state” with the values of “true” and “red” (see the UserParameters function for details regarding accessing the parameter).
Note: When using GetRespondentUrl to pass several text values into the start of the interview, a semicolon ; is used as a separator. If a ; is required as part of the parameter, it must be encoded.
The plus sign + must also be encoded if used as a parameter.
In this example,
GetRespondentUrl("cb1", true, "alert=true")will give a link that when opened, will open the survey for the current respondent at the start of the call block named “cb1”, passing the encrypted parameter named alert with a value of “true” (see the UserParameters function for details regarding accessing the parameter). When the respondent finishes the callblock, the interview will finish.
Note: When GetRespondentUrl is used to access a callblock, the interview_start, interview_end and interview status values are not updated during the callblock interviewing session. However, if the callblock contains a STOP node then interview_end and >interview status will be updated.
ImportantGetRespondentUrl should not be used to start the interview at a question contained within a callblock as the interview will fail when the respondent reaches the end of the callblock.GetRespondentUrl access to a callblock will cause the interview to finish when the callblock is completed. It is not designed to act as a scripted way to access a callblock.GetRespondentUrl must not be used with CATI; use GetCatiRespondentUrl(go to GetCatiRespondentUrl for more information).
Building a Cryptic URL to be displayed in an info node
Even for the respondents who answer open surveys (for example pop-ups), a unique URL can be used to reenter the survey.
So if you want respondents to an open survey such as for example a pop-up survey to be able to quit in the middle of the survey, close their browser and then continue later, they just need to have the correct link with the respondent-specific parameter. They will then be able to enter their own survey with previous answers intact. Without this link, they will have to start on a new survey.
To achieve this, one solution is to display the respondent-specific URL in the interview, instructing the respondent to copy that exact URL if they want to pause and continue later, for example:
Figure 6 - Reentry url example
In the example above, the survey setting “Encrypt System Request Parameters” is set. If this is disabled, the link will have r=respid&s=sid instead of __sid__. GetRespondentUrl supports either option for respondent-specific URLs.
You can insert the respondent-specific URL in the text area of an info node as follows:
^GetRespondentUrl()^The same functions can be used to email a personal link to a respondent (go to SendMail for more information).
RedirectToRespondentUrl
RedirectToRespondentUrl()Calling this function will result in an internal redirect to a specific location within the survey. This is similar to Redirect(GetRespondentUrl()), but without resulting in seeing the new URL.
- If this function is used in an offline survey channel (not Web or CATI), it will be equivalent to calling
Redirect(GetRespondentUrl(…), true). - In JavaScript survey engine, the function has only one supported signature:
RedirectToRespondentUrl(string questionId, bool isCallBlock, string userParameter, params string[] loopiters). In jScript.NET survey engine supported signatures are the same asGetRespondentUrland all its features (such as redirect to CallBlock and passing custom parameters) . Refer to GetRespondentUrl, above, for more information.
Note that a parameter must be passed. No parameters, that is RedirectToRespondentUrl() on its own, is not supported.
CurrentID
CurrentID()CurrentID returns the respid of the current respondent. Note that this does not necessarily apply to CAPI interviews; CurrentID on the CAPI Console returns the CAPI local respondent ID.
Using modulus to route respondents to different parts of the questionnaire
You can use the remainder of respid divided by a number x to route respondents to x different parts of the questionnaire in rotation. For example, if you have three sections A, B and C, you can create a pattern as:
respondent 1 would complete section B,
respondent 2 would complete section C,
respondent 3 would complete section A,
respondent 4 would complete section B,
respondent 5 would complete section C,
respondent 6 would complete section A,
etc.
This can be done by using the CurrentID() function and modulus / remainder. Depending on the result of
CurrentID()%3the respondent is routed to the appropriate part of the questionnaire.
Figure 7 - CurrentID in use
See also GetResponseID().
CurrentLang
CurrentLang()CurrentLang returns the language code of the current language used (e.g. 9 for English). This can be used e.g. in conditions if you want different routing for different languages. You can also use it to set hidden questions to use in reporting if you want to report on the different languages.
CurrentPID
CurrentPID()CurrentPID returns the project number of the survey (a number prefixed by p). This can for example be set in a hidden variable to be used in data exports if you export from several surveys into a common format.
CurrentLoops
CurrentLoops()CurrentLoops is used in validation code, masking and in response piping in a question's text fields (or in functions called from validation code, masking and response piping) and returns the IDs of all loops that the current question is located in. Calling CurrentLoops() as a function returns an array of strings containing the loop IDs, with the first (or outer) loop at the start of the list. It will also return a list with one element in it so it is possible to get the loop ID with CurrentLoops()[0] or CurrentLoops().ToString().
GetRespondentValue and SetRespondentValue
Sometimes you may want to be able to modify values from the respondent list. Through the "background variable" property in survey questions, values can be fetched from the respondent list and set in the survey data. However you cannot use these to update the respondent list; it is one-way only.
One scenario where it would be beneficial to update the respondent list is if you have a survey which the respondents continuously update, and you want to keep sending new reminders to the respondents. If they change their email address in the survey, you would like the respondent list updated with the new email address so that new reminders are sent to the new email address.
GetRespondentValue(fieldname)will return the value uploaded in the fieldname (string) column in the respondent list for the current respondent. If the fieldname does not exist, null will be returned.
SetRespondentValue(fieldname,value)will set fieldname (string) in the respondent list to value (string) for the current respondent. If fieldname does not exist, nothing will happen. There are three system fields that can not be updated: rid, sid and rowguid. Attempting to update any of these will give a script error.
Calculating the number of days elapsed since a record was uploaded
The following script works out the number of days passed since a record was uploaded in the respondents database.
JScript example:
f('UploadDate').set(GetRespondentValue("CreatedDate"))
//where UploadDate is a date type question
var created = new Date(GetRespondentValue('CreatedDate'));
var d = created.getDate();
var m = created.getMonth() + 1;
var y = created.getFullYear();
var start : DateTime = new DateTime(y,m,d);
var now = new Date();
var end : DateTime = new DateTime(now.getFullYear(), now.getMonth() + 1, now.getDate());
var span : TimeSpan = end - start;
var days = span.TotalDays;
f('nodays').set(days)
JavaScript example:
f('UploadDate').set(GetRespondentValue('CreatedDate'));
var created = new Date(GetRespondentValue('CreatedDate'));
var today = new Date();
const elapsed = today.getTime() - created.getTime(); //timespan in miliseconds
var elapsedDays = elapsed / (1000 * 60 * 60 * 24); //convert miliseconds to days
var days = Math.round(elapsedDays); //round number of days
f('nodays').set(days);
InterviewStart InterviewEnd SetInterviewStart and SetInterviewEnd
When a respondent opens a Forsta Plus survey, an SQL variable called interview_start is set with the exact time and date. When the respondent reaches a stop node or the end of the interview, an SQL variable called interview_end is set. These variables can be used in reporting and are included in data exports. Reporting on time series is for example based on interview_start.
Note: If a respondent re-enters the interview, interview_start is re-set, and similarly, if she or he reaches a stop node or the end of the interview after re-entering a completed interview, the variable interview_end is also re-set.
Two functions can be used to get the values of these timestamps in scripts
InterviewStart() InterviewStart returns the respondent’s interview start time.
SetInterviewStart(date)SetInterviewStart sets the respondent’s interview. The parameter date is optional. If it is not included, interview_start will be set to current server time and date. If date is included, it can either be a JScript.NET Date object or a .NET DateTime object.
InterviewEnd()InterviewEnd returns the respondent's interview end time.
We will return to examples on how to use these functions later in the documentation (go to InterviewStart and InterviewEnd for more information) where they are used together with the Date object.
There are also two functions available to set these timestamps. SetInterviewStart can be used for example when you want interview start to be set after the screening questions of a survey instead of at the beginning of the survey, and SetInterviewEnd can be used to set the interview end timestamp when a stop node is never reached because of a redirect at the end of the survey (go to Redirect for more information).
SetInterviewStart() - sets the respondent’s interview start time to current server time and date.
SetInterviewEnd() - sets the respondent's interview end time to current server time and date.
GetStatus and SetStatus
When the respondent reaches a stop node, status is set according to the status defined for that stop node. When the respondent reaches the end of the interview, status is set to "complete".
.
Figure 8 - Interview status after stop node
Currently Forsta Plus recognizes the following status settings:
Status |
Code |
Complete |
complete |
Screened |
screened |
Quota Full |
quotafull |
Error |
error |
If status is null, it means that the interview is incomplete. The "error" status is set if the interview terminates because of an error in a script.
There are two functions that operate on status:
GetStatus()GetStatus returns the current interview status.
SetStatus(status)SetStatus can be used in a script to set the interview status, e.g. if you want respondents who have answered the questionnaire up to a certain point to count as complete interviews, even though they do not answer all the remaining questions. status is a string with the status value you want to set, i.e. "complete", "screened" or "quotafull". SetStatus is very often used in combination with the Redirect function (go to Redirect for more information).
The SetStatus function will just set the interview status, not the interview_end time stamp. interview_end is just set when the end of the interview or a stop node is reached.
Note: The use of redirects, quotas, status-screened or other solutions with the principle purpose of avoiding the survey "complete" status being reached by a respondent having offered a reasonable amount of responses, is prohibited and will be regarded as an attempt to avoid transaction fee obligations to Forsta.
Setting Interview Status Before End of Survey
If you want to set the status of the interview to "complete" before the last questions (which e.g. could be questions about personal details on where to send incentives etc.), you can include a script node with the following code where you want the status to be set:
SetStatus("complete");If you do this, even respondents that do not answer those last questions with personal details will still count as completes for reporting etc.
Forward
Forward()Forward returns true if the respondent is moving forward through the questionnaire (has clicked on the forward button), and false if the respondent is moving backward (has clicked on the back button). This can be used for code that you only want to execute when the respondent moves in a particular direction.
There is no point in using this function in validation code, because validation code is only run when the respondent moves forward in the questionnaire.
IsInRdgMode
IsInRdgMode()IsInRdgMode returns true if the scripts are executed during a Random Data Generator run, false otherwise. You may use this function to prevent some script code from being run when testing the surveys with the RDG.
SetRandomCategories
SetRandomCategories(number, qid)SetRandomCategories can be used to randomly switch on the specified number of categories of the specified question ID. Typically this would be used to randomly turn on number categories of a specific hidden qid. In the example below, two categories of the hidden question q2 would be switched on.
SetRandomCategories(2, 'q2')This function is only applicable for standard multi questions. It does not apply to multi questions with the Capture Order property set.
TerminateLoop
TerminateLoop()TerminateLoop is used inside of auto-increment loops. Auto-increment loops are only available for optimized database projects. A TerminateLoop call is required to stop further iterations of the loop being created. Without this, the loop will continuously create new loop iterations, and the respondent will never be able to finish the loop.
A script node containing a TerminateLoop function call is a mandatory requirement for an auto-increment loop because an auto increment loop iteration requires some interactive content for the respondent (question, info node etc.). If the loop contains nothing interactive, the interview will be terminated with an error status and an error notification will be sent via email.
Note that the TerminateLoop function call must be placed at the end of the loop to have any effect.
In the following example the loopTermination script node contains the single function call TerminateLoop and is used to prevent further iterations of the auto-increment loop based on the answer to the "continue" question.
Figure 9 - loopTermination in use
TerminateLoop calls are only applicable to auto-increment loops; they are not applicable to, and have no effect on loops based on normal answer lists or those based on table lookups.
IsAccessibleMode and SetAccessibleMode
IsAccessibleMode()IsAccessibleMode returns true if the current Survey Layout Theme is a theme in Accessible mode. The function is useful if you some respondents are responding in accessible mode and some not, and you would like different content in the two modes.
SetAccessibleMode(bool)SetAccessibleMode can be used to either set the survey in accessible mode (i.e. switch to a Survey Layout Theme that is set as Accessible):
SetAccessibleMode(true)or to set the survey not to be in accessible mode (i.e. switch to a Survey Layout Theme that is not set as Accessible):
SetAccessibleMode(false)
UserParameters
UserParameters[paramName]UserParameters can be used to access texts that are passed to the start of the interview using the GetRespondentURL() function.
In this example,
UserParameters["alert"]will give the value that the parameter named “alert” was set to when GetRespondentUrl was used to access the survey.
Note: UserParameters can only be used on the first page that the respondent is directed to via GetRespondentUrl. UserParmeters will return empty values if used later in the survey.
To access all parameter information UserParameters.Keys can be used. The Keys function returns a NameValueCollection which can be iterated through.
In this example, a script function “ShowKeys()” has been created to display all parameter information.
JScript example:
function ShowKeys()
{
var str = "";
for(var x = new Enumerator(UserParameters.Keys); !x.atEnd(); x.moveNext())
{
var y = x.item();
str += "<br />" + y + " = " + UserParameters(y);
}
return str;
}
JavaScript example:
function ShowKeys() {
var str = "";
UserParameters.AllKeys.forEach(key => {
str += "<br />" + key + " = " + UserParameters.item(key);
});
return str;
}
But actually, the same function can be shortened to:
function ShowKeys() {
return UserParameters.AllKeys.map(key => key + " = " + UserParameters.item(key)).join("<br />");
}
When piping the result of this function, for example using ^ShowKeys()^ in an interview initiated via GetRespondentUrl("", false, "alert=true;state=red") the following the following will be displayed:
Figure 10 - ^ShowKeys()^ function in use
Note: Survey links in hitlists can have parameters added to the link. Two functions are available to receive the value from the link; UserParameters and Request(go to Request for more information). The function you must use depends on the link's “Link type” setting. UserParameters will only be able to retrieve the value from the hitlist link when "Link type" in the Hitlist Field Properties page is set to "Encrypted URL parameters". Refer to the separate Reportal documentation for further details.
GetDeviceInfo
GetDeviceInfo()GetDeviceInfo() is a scripting function that returns an object containing a variety of information regarding the type of device that is being used by the respondent.
Note: The information returned is dependent on the rendering modes enabled for the survey. For example, if mobile rendering channel is not enabled in Survey Settings then IsTablet will return False.
The object returned contains the properties described in the following table:
| Property Name | Type | Value | Meaning |
| IsGeneric | Boolean | true or false | Returns true if the respondent is using a generic mobile device. |
| IsDesktop | Boolean | true or false | Returns true if the respondent is using a desktop device. |
| IsTouch | Boolean | true or false | Returns true if the respondent is using a touch mobile phone device, for example an iPhone or Android phone (not iPad; this returns false - see the Important note below). |
| IsTablet | Boolean | true or false | Returns true if the respondent is using a tablet device. Note that iPad returns false. |
| IsMobile | Boolean | true or false | Returns true if the respondent is using a mobile device (phone or tablet). Note that iPad returns false. |
| ScreenResolution | String | “600|400” or “0|0” | The screen resolution of the device being used width|height or “0|0” if unknown. |
| DeviceType | String | "Desktop", "Touch", "Generic" | The device type in use. |
| DeviceType.toString() | String | "Desktop", "Touch", "Generic" | The device type in use. |
For example, an info node containing the following:
The results of the function calls are:
GetDeviceInfo().IsDesktop: ^GetDeviceInfo().IsDesktop^
GetDeviceInfo().IsTouch: ^GetDeviceInfo().IsTouch^
GetDeviceInfo().IsTablet: ^GetDeviceInfo().IsTablet^
GetDeviceInfo().IsGeneric: ^GetDeviceInfo().IsGeneric^
GetDeviceInfo().IsMobile: ^GetDeviceInfo().IsMobile^
GetDeviceInfo().ScreenResolution: ^GetDeviceInfo().ScreenResolution^
GetDeviceInfo().DeviceType: ^GetDeviceInfo().DeviceType^
GetDeviceInfo().DeviceType.toString(): ^GetDeviceInfo().DeviceType.toString()^
Will return the following information on an iPhone 4:
Figure 11 - GetDeviceInfo example
Note: ScreenResolution will only be available if Smartphone rendering mode is enabled and the device is either a touch or tablet device.
Note: The definition of "Tablet" is a device with a user agent string conforming to the UserAgentRegExTouchDevice expression from System Configuration that also has at least one screen dimension exceeding 650px.
When only Desktop mode is enabled, the screen resolution check is not performed so IsTablet will always return false.
Important
Screen dimension is often considered to be the actual screen resolution that is advertised on a phone’s specification sheet (i.e. the screen.width and screen.height * the device pixel ratio). If you are using and relying on the GetDeviceInfo().ScreenResolution information in your survey, be aware that Forsta Plus uses the viewport’s width and height (that is window.innerWidth and window.innerHeight). Forsta Plus also uses the CSS Interpretation (the resolution / the device pixel ratio) divided again by the device pixel ratio. These are the numbers that are returned for GetDeviceInfo().ScreenResolution, and the numbers used to determine tablet.
Important
Be aware that although iPad is classified as a tablet device, iPad is included in the desktop regex (the UserAgentRegExDesktop expression from System Configuration) that is configured for Forsta Plus. Therefore if a respondent is taking a survey on an iPad device, IsTablet and IsTouch will never return true; it only gets as far as the first check (the user agent string) and returns false.
GetQuestionIds
GetQuestionIds is used to return a string array of question IDs based on specific filters provided.
GetQuestionIds(questionTypes: String[], variableTypes: String[], loopId: String)
GetQuestionIds(includeInteractiveQuestions: Boolean, includeNonInteractiveQuestions: Boolean, loopId: String)
Where:
questionTypes is a string array that filters and lists questions which are of a specific type only. The types are (case insensitive): "single", "multi", "grid", "ranking", "open text list", "numeric list", "open", "numeric", "date", "geolocation", "imageupload", "multigrid" and "3dgrid".
variableTypes is a string array which filters and lists questions which are of a variable type, the types are (case insensitive): "normal", "panelvisible", "hidden", "background", "recoded" and "recoding“.
loopId filters and lists questions inside the specified loop only (not recursive).
includeInteractiveQuestions if set true will filter and list all questions that have normal or panel visible variable types.
includeNonInteractiveQuestions if set true will filter and list all questions that have hidden, background, recoded and recoding variable types.
Note that only root nodes of multigrids and 3dgrids are listed. It is possible to get title, text and instruction of a multigrid or a 3dgrid using f(g1).text() or .label() or .instruction().
In this example,
GetQuestionIds(true, false)will return a string array of all interactive questions in the survey.
In this example,
JScript example:
var questionsTypesIncluded : String[] = ["open", "numeric"];
f("myQuestions").set(GetQuestionIds(questionsTypesIncluded).toString());
JavaScript example:
var questionsTypesIncluded = ["open", "numeric"];
f("myQuestions").set(GetQuestionIds(questionsTypesIncluded).toString());
will set the ”myQuestions” answer to be a comma-separated list of all open text and numeric questions in the survey.
Get3DGridQuestionIds
Get3DGridQuestionIds is used to return a string array of the questions inside a specific 3DGrid, and will also return the row question ids of a multigrid when the multigrid id is used as the function argument.
Get3DGridQuestionIds(gridId: String)Where:
gridId is the question ID of a 3Dgrid.
In this example,
Get3DGridQuestionIds("g1").toString()will return a comma-separated list of all question IDs inside the 3DGrid “g1”.
As a Multigrid object is a transposed 3D Grid, this function can also be used to retrieve the Question (row) ids of a multigrid.
Note: When the Multigrid or 3D Grid contains an Other - Specify answer option then the form name will be returned in the array as the first element.
GetSurveyPackageVersion
GetSurveyPackageVersion()The GetSurveyPackageVersion function can be used to return the internal survey package number for the survey currently being used. This information can be useful when ensuring that a specific version of the survey is being used.
GetCompanyID
GetCompanyId()GetCompanyId can be used to get the ID of the company that this survey belongs to. The CompanyId is an int.
GetSurveyName
GetSurveyName()GetSurveyName can be used to get the name of the current survey, as a string value.
GetResponseId
GetResponseId()This gives the response ID of the current interview record. Use example: The text below could be added to a text field.
The Response ID allocated to this interview is: ^GetResponseId()^
This function can also be used in scripting.
See also CurrentID().
GetLanguageCodes
GetLanguageCodes()GetLanguageCodes() can be used to return a set of language IDs that exist for the current survey. This can be used to check if a specific language code/s is valid in a survey, or it can be used as a mask on a question, based on the available languages. In the example below - the function is used to return a set of available languages, then based on the language codes and the answer codes, the answer list will be filtered to only display the languages available in this survey.
Figure 12 - GetLanguageCodes example
Example of the GetLanguageCodes function in use
FormExists
FormExists(string qid)FormExists() is used to check if a specific form exists in the current survey. The function returns true if the form exists in the survey, false if it does not. For example the script below checks if q1 exists:
var qid = "q1";
var questionExists = FormExists(qid);
This can be used in scripting to ensure that a form actually exists, before referencing it.