You can use the pulldata("@javascript") function to invoke JavaScript functions, allowing you to use advanced techniques and logic beyond what is possible through XLSForm alone.
You must store your custom JavaScript files in a folder named scripts in the survey directory.
Basic syntax
You can invoke custom JavaScript functions to return values. Use the following syntax to invoke custom JavaScript functions with the pulldata("@javascript") function:
pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")
In the example above, the JavaScript function expects two parameters, but you can add any number of function parameters.
Other questions in the survey can be used as parameters for pulldata("@javascript") functions. In the following example, the answer to the project_code question is passed into the projectLookup function:
pulldata("@javascript", "projects.js", "projectLookup", ${project_code})
Note:
Setting geopoint, geotrace, or geoshape questions as parameters for pulldata("@javascript") functions is not supported in Survey123 Studio and Survey123 Mobile.
You can use the pulldata("@json") function to extract specific values from a JSON object produced by a JavaScript function. For more information, see Retrieve a value from JSON.
Sometimes, particularly when using JavaScript to access web services and secure ArcGIS services, you may need access to device and user properties. You can use the pulldata("@property") function to extract information about the devices from which survey responses are submitted, and the signed-in users who submit these responses. For more information, see Device, user, and survey properties.
Tip:
For spatial and attribute queries on ArcGIS feature layers, consider using the pulldata("@layer") function instead of pulldata("@javascript"). The pulldata("@layer") syntax is specifically designed for feature layer queries and is supported for public surveys. For more information, see Query a feature layer.
Repeats
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
You can pass all values from across a repeat into JavaScript functions. The pulldata("@javascript") function supports two styles of implementation for retrieving the values from a repeat. The one to use depends on whether you want the JavaScript function to interact with one field or many fields in a repeat.
If a question from a repeat is passed in as a function parameter, the JavaScript function receives an array of values from the specified question, as follows:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})
If a repeat name is passed in as a function parameter, the JavaScript function receives the parameter as an array of rows of all the values in the repeat, as follows:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")
Each of these produces a JSON object with individual questions as properties in that object.
Note:
Accessing values in repeats using pulldata("@javascript") is not supported in the Survey123 web app. You can collect values for a single question in a repeat in the web app using join() to convert the list of values into a character-separated string and split the values in the JavaScript function.
As of Survey123 version 3.14, empty values passed through a JavaScript function can now return either undefined or null. Because of this, you must write JavaScript functions to account for the possibility of an undefined value.
Known limitations
The following are known limitations when using JavaScript functions in survey forms:
- Document Object Model (DOM) is not supported.
- Frameworks such as JQuery, Ember, and Angular are not supported.
- You cannot access local files.
- Asynchronous calls are not supported.
- JavaScript functions are only supported in forms completed by users in the same organization as the form author.
- JavaScript functions are not supported for public surveys.
- A pulldata("@javascript") function cannot be called inside a pulldata("@json") function on the Survey123 web app.
Script tools
Note:
This section describes functionality that is only available in Survey123 Connect. This functionality is not available in Survey123 Studio.
You can manage and edit JavaScript functions on the Scripts tab of Survey123 Connect. On this tab, you can create a JavaScript file, review the code, and test the function. This tab is not a complete replacement for an integrated development environment (IDE), which can provide code validation and best practice analysis to help develop JavaScript functions, but the tab is designed to assist with the integration of these functions in Survey123.
The following tools are available on the menu of the Scripts tab of Survey123 Connect:
- Script files—Show all JavaScript files in the scripts folder of a survey. Select a file to view and edit.
- Open scripts folder—Launch the file browser at the location of the scripts folder of a survey.
- New script file—Create a script file in the scripts folder of a survey. Type the file name and click Create.
- Select function—Highlight the first function in the opened file and present the parameters for testing.
- Save—Save changes to the opened file.
- Launch external editor—Launch the system's default JavaScript IDE with the opened file.
Click the Select function tool to test the behavior of the first function in the file by typing values for each parameter and viewing the output. Once you are finished with the function, you can copy the pulldata statement presented here and paste it in the XLSForm. If you are signed in to your organization, right-click any of the parameters and click Paste token, if required.