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 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.
Script tools in Survey123 Connect
The following tools are available on the menu of the Scripts tab of Survey123 Connect:
- Script files—Show all JavaScript files located 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.
Note:
Basic syntax errors are shown on the Scripts tab with an error indicator next to the line number. Error handling must be implemented inside the JavaScript function. Console output is displayed on the Scripts tab, so by including console messages in your function, you can see errors, warnings, and information messages displayed along with the output.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")
You must store your custom JavaScript files in a folder named scripts in the survey directory. In the example above, the JavaScriptfunction expects two parameters, but you can add any number of function parameters.
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 and user 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
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.