JavaScript - Survey & Question Functions

Only users who have experience with JavaScript should use this feature. Please contact us if you need assistance adding JavaScript.

JavaScript (JS) is a programming language that is read, interpreted, and executed in your web browser.

It can be used to trigger a behavior or validation on a survey form, based on certain events tied to the survey or a question.

For example, you could add JavaScript to:

• Extract a location ID from a receipt number, then map that location ID to the location's hierarchy node ID, and then add the hierarchy node ID to the record as metadata, which could then be used to set up show/hide skip logic on the form.

To add JavaScript to a survey question/element:

• Click on Add JavaScript in the question/element settings and then choose the type of event(s) (ON LOAD, ON CHANGE, etc.) that will execute the JS.
• Enter the JavaScript for the event(s) into the interface and click on OK.
• Save the question/element to complete the process.

ON LOAD

The JS will be executed anytime the section/page containing the question with the JS is loaded.
For example, if a survey page contains some JS it will execute when the page first loads, and it would execute again if the respondent presses the BACK button to return to that page at any time.

ON CHANGE

The JS will be executed whenever the question's value changes. E.g. The respondent enters or edits a response.
Note: JS for this event will execute on load if a default response has been set in the question settings.

ON SHOW

The JS will be executed only when a question which was hidden becomes visible due to survey logic that has been applied.

ON HIDE

The JS will be executed only when a question which was shown becomes hidden due to survey logic that has been applied.

GLOBAL SURVEY FUNCTIONS

Global functions are available by accessing the IntouchSurvey global variable. These functions can be used to access metadata, enabling/disabling previous/next buttons and more complex logic.

Metadata Functions

Add Metadata

Definition:

IntouchSurvey.addMeta(key:string, value:any):void;

• Adds metadata to the survey record.
• Metadata can be used for custom logic or tracking additional data.
• Metadata is stored by a key/value pair, where the key is a way to access it and the value is the information you want to read/add.

Example:

IntouchSurvey.addMeta("promo_name", "savings4you");
// adds "promo_name": "savings4you" to the record's metadata 

 

Remove Metadata

Definition:

IntouchSurvey.removeMeta(key:string):void;

• Removes metadata from the record.
• If you have added a custom metadata key there may be circumstances when you want to remove the metadata stored under that specific key from the record entirely; you can do so using the metadata key.

Example:

IntouchSurvey.removeMeta("promo_name");
// removes "promo_name" from the record metadata 

 

Get Metadata

Definition:

IntouchSurvey.getMeta(key:string):any;

• Retrieves the specified metadata from the record.
• In some scenarios, you may want to do some further verification or changes based on the metadata currently available with the record. You can access the metadata using its key.

Example:

var metaRetrieved = IntouchSurvey.getMeta("promo_name");
// returns "savings4you"

 

Get All Metadata

Definition:

IntouchSurvey.getAllMeta():any;

• Retrieves all metadata from the record.
• If you need to do multiple verifications or changes, you can retrieve all the metadata
  currently available for the record.

Example:

var allMeta = IntouchSurvey.getAllMeta();
/*
returns an object like so:
{
 "promo_name": "savings4you"
}
*/

 

Survey Navigation Functions

Disable/Enable NEXT Button

Definition:

IntouchSurvey.disablePrevious():void; 
IntouchSurvey.enablePrevious():void;

• Sets the NEXT button on the survey page to an enabled (can be clicked) or disabled (cannot be clicked) state.
• This is used to manually control the ability to continue the survey after manual validation/changes. For example, if a variable entered by a respondent is found to be invalid, they will be unable to click the NEXT button to proceed further on the survey until they enter a valid variable.
• Information should be provided to the user to explain how to re-enable the disabled button. E.g. A popup, display text, etc.
• IMPORTANT: If the JS disables the next button, you must have a scenario where it becomes enabledor the user will not be able to complete the survey.

Example:

if(someArbitraryVariable === "123"){
 IntouchSurvey.enableNext();
} else {
 IntouchSurvey.disableNext();
}

 

Disable/Enable BACK Button

Definition:

IntouchSurvey.disablePrevious():void; 
IntouchSurvey.enablePrevious():void;

• Sets the BACK button on the survey page to an enabled (can be clicked) or disabled (cannot be clicked) state.
• This is used to manually control the ability to go to previous page of the survey after manual validation/changes. For example, if a variable entered by a respondent is found to be invalid, they will be unable to return to the previous page on the survey until they enter a valid variable.
• Information should be provided to the user to explain how to re-enable the disabled button. E.g. A popup, display text, etc.
• IMPORTANT: The JS should include the script to enable the BACK button to ensure it does not remain in a disabled state.

Example:

if(someArbitraryVariable === "123"){
 IntouchSurvey.enablePrevious();
} else {
 IntouchSurvey.disablePrevious();
}

 

Disable/Enable SUBMIT Button

Definition:

IntouchSurvey.disableSubmit():void; 
IntouchSurvey.enableSubmit():void;

• Sets the SUBMIT button on the last page of the survey to an enabled (can be clicked) or disabled (cannot be clicked) state.
• This is used to manually control the ability to submit the survey after manual validation/changes.
• Typically this would be used when applying custom logic on the final page but it may be used to stop submissions at any point in the survey.
• Information should be provided to the user to explain how to correct the variable that disabled the button. E.g. A popup, display text, etc.
• IMPORTANT: If the JS disables the submit button, you must have a scenario where it becomes enabledor the user will not be able to complete the survey.

Example:

if(someArbitraryVariable === "123"){
 IntouchSurvey.enableSubmit();
} else {
 IntouchSurvey.disableSubmit();
}

 

Survey Record Functions

Set Record Location

Definition:

IntouchSurvey.setRecordLocation(uuid:string):void;

• Sets the record's location node based on the UUID that is passed. Location nodes are found in your organization's hierarchy structure.
• Setting a record's location manually allows the record to be assigned to the specified hierarchy location node in IQ.
• If no node is manually assigned, the record will roll up under the root node of the hierarchy, unless a Location element is added to the survey to collect the location detail.
• IMPORTANT: Must be a valid location node UUID for proper reporting.

Example:

IntouchSurvey.setRecordLocation("jhd12hjg-hkj123khj-123jk123kj");

 

Set Record Date

Definition:

IntouchSurvey.setRecordDate(date:string):void;

• Sets the record's date of submission using the date that has been retrieved from a Calendar element on the survey.
• Supported format is "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS".
• Note: This behaviour can easily be enabled using the Set as submission date feature in the advanced options on the Calendar element.

Example:

IntouchSurvey.setRecordDate("2019-01-01 08:13:43");

 

Verify Metadata on Record

Definition:

IntouchSurvey.recordExists(metadata:any):void;

• Validate if a record was submitted containing specified metadata.
• Returns 200 if the record exists and 404 if it is not found.

Example:

IntouchSurvey.recordExists({
 promo_name: "savings4you"
}).then(function(){
 // handle if the record exists
}).catch(function(){
 // handle if the record does not exist
});

Miscellaneous Survey Functions

Get Current Language

Definition:

IntouchSurvey.getCurrentLanguage():string;

• Retrieves the survey's current language setting.
• The language setting can then be used to control, for example, which translation of a pop up should be displayed to the respondent.

Example:

IntouchSurvey.getCurrentLanguage();
// return fr_CA, en_US

 

Display Pop Up

Definition:

IntouchSurvey.popup(text:string, button:string):ng.IPromise<any>;

• Displays a pop up (modal) with text and an acknowledgment button for the user.
• This adds no information to the record and is only used to convey information.

Example:

IntouchSurvey.popup("Please confirm the receipt number you entered is correct", "OK");
// will show a popup box with text saying: Please confirm the receipt number you entered is correct
// and a button with the text: OK

QUESTION SPECIFIC FUNCTIONS

Question specific functions are available when applying custom JavaScript to a survey question. The JavaScript will expose the "this" keyword with access to question-specific functionality.

IMPORTANT: For more advanced users who will be using events or HTTP requests, you may need to assign this to a variable to access it within the callback function's scope.

Advanced Example:

var self = this;

document.onclick = function(){
  // this.setValue("123") <-- this will not work
  self.setValue("123"); // <-- this will work

  /*
  Since changes happened to models outside of 2-way bound functionality,
  we need to manually sync the survey.
  For more information, see the sync global function section.
  */
  IntouchSurvey.sync();
}

 

Is Valid

Definition:

this.isValid():boolean;

• Returns if the question is currently valid.

Example:

if(this.isValid()){
 // handle if valid
} else {
 // handle if invalid
}

 

Get Value

Definition:

this.getValue():any;

• Returns the current value of the question.

Example:

if(this.getValue() == "123"){
 // the value is equal to "123"
} else {
 // the value is not equal "123"
}

 

Is Hidden

Definition:

this.isHidden():boolean;

• Returns if the question is hidden.
• A question can be hidden if Show/Hide logic has been applied to hide it.

Example:

if(this.isHidden()){
 // handle if hidden
} else {
 // handle if visible
}

 

Is Visible

Definition:

this.isVisible():boolean;

• Returns if the question is visible.
• A question can be visible if no logic is applied to hide it, or if logic is applied to show it only under certain circumstances.

Example:

if(this.isVisible()){
 // handle if visible
} else {
 // handle if hidden
}

 

Set Value

Definition:

this.setValue(value:string|number):void;

• Programmatically sets the value on a text input element (string) or a slider (number), NPS^® (number), or rating question (number).

Example:

this.setValue("75");

// Record question value will be set as "75"

this.setValue("Excellent");

// Record text input will be "Excellent"

 

Set Response

Definition:

this.setResponse():void;

• Programmatically select a response on a multiple choice, dropdown, or checkboxes question by index or response label.

Example:

Response Index	Example Response Labels
0	Earth
1	Jupiter
2	Mars

// Setting via index (first response is 0 indexed):
this.setResponse(0);

// Sets the response to "Earth"


// Setting via response label:
this.setResponse("Jupiter");

// Sets the response to "Jupiter"