JavaScript in Experience Cloud
Reserved name and text pattern: x_* and xx_*
// This comment contains 'x_nothing', which is the reserved pattern and cannot be
// used. Similarly, the following variable name is the reserved pattern.
var f_counter = 0;Execution timing
When writing code, it's important to understand when it will be executed, as this affects the context of information that will be available at run-time. Knowing how often the code will run is also important to estimate what kind of impact it will have on performance.
Surveys
JavaScript can be executed in surveys as part of the following:
-
Display logic.
-
JavaScript validation.
-
Embedded in an HTML element.
Display rules and conditions exist for Survey distribution, Page logic, Content group logic , as well as the Content logic in the survey.
Display logic is executed right before a survey page is loaded on a survey taker's browser, and determine if the survey is distributed, or if the page, group, or content element the rule belongs to is displayed or not. If the condition evaluates to Yes (true), then the survey is distributed, or the page, group or content element is included in the survey; if it evaluates to No (false), then the survey is not sent out, or the page, group, or element is never seen by the survey taker.
JavaScript validation is executed when the survey taker clicks to pass the page that the element belongs to. For example, a JavaScript validation that belongs to a question executes when the survey taker clicks Next on that page. JavaScript validations are often used to set fields based on survey answers, these calculations can then be used to condition the content displayed in the following pages. They are also used to validate an answer, for example to check that the number of characters entered into a text field is valid.
SCRIPT("") to make them JavaScript. Otherwise, they are treated as Conditional expressions.$(dom-selector).action() may not function correctly and could cause custom HTML to render improperly. jQuery is not available in instances not already using it. K- fields
K- fields are tied to records, so a separate calculation is performed for each record. The calculation can reference other values in that same record, such as Feedback fields, it can also reference organizational structures and lookup tables.
The JavaScript in a K-field runs automatically any time that the record changes, it also runs every time the record is exported or viewed in a responses report.
R-fields
R-fields are closely tied to reports, so a single calculation is performed for all of the values in an entire row (or column, depending on the orientation) of the report. They deal with aggregate values across survey records rather than at an individual survey level, they can access this data through the Cube object. A single R-field can be used by multiple different reports.
The JavaScript in an R-field runs every time you open one of the reports that uses it.
Custom modules
Custom Module (formerly known as AA2's) describe a report and may include JavaScript snippets, and they can reference R-fields that perform their own calculations. Like R-fields, custom modules deal with aggregate values across survey records rather than individual surveys.
The JavaScript in a custom modules runs every time you open the report. Report column calculations are computed first, and then the row calculations.
Importer processors
Importer processors parse input files to produce new records. The processor is primarily written in XML, but you can add JavaScript snippets to calculate the value of a field based on the values of other fields, these calculations can also reference org hierarchies, lookup tables, etc.
JavaScript in importer processors runs once for each record that is imported as part of the import task.
If there are preprocessors in place to change the data format before importing (like CSV to JSON or regex rules), then the JavaScript code can only access the data that has already been handled by these preprocessors.
The JavaScript code embedded in an import specification can reference the values of fields that were generated in prior lines of the same import specification.
About the Cube
The Cube object can be used by a report to access data from the in-memory database (previously known as Slug).
When opening a report, a single cube object is generated on the fly based on the fields that exist in the report. It presents this information as a multi-dimensional object and can be accessed via the name 'cube' from anywhere in the JavaScript code of a Custom module or from any R-field that is used by the report.
cube methods only work on Custom modules; R-fields that use these methods must only be referenced by custom modules, as they would fail if referenced by other types of reports. To write code for an R-field that uses these methods, deselect Disable validation on the new R-field screen. cube object has several methods that can be called from one of its instances, for example: cube.cut('e_status', 'COMPLETED').The operation above returns a new cube object which is a filtered version of the original, as it only includes records with the value 'COMPLETED' in the e_status field. The original cube object is not modified by executing this method, and still contains all the records it used to have.
Each method can either return a single aggregate value or a new cube object, but can't modify the original cube in any way.
Cube methods can be stringed together in a same line using a . character, so that each method is performed on the resulting cube from the previous one: cube.cut('e_status', 'COMPLETED').getAvg('q_main_score') .
In the example above, the cut method first filters the cube and generates a 'smaller' cube with only the records that match the condition, then the getAvg operation uses this new cube to calculate the average of the q_main_score field for only the records that were left after filtering.
