This article provides a checklist for troubleshooting JavaScript (JS) code used in Variables, Rules, and QScripts. A list of Helpful Functions used to Troubleshoot is at the end of the document for quick reference.
1. Gather the details about the issue
2. Find what is causing the issue
3. Figure out a workaround or a solution
Helpful Functions used to Troubleshoot
Requirements
- A JavaScript-based variable, Rule, or QScript.
- Familiarity with the tips on writing JavaScript code in JavaScript Fundamentals, which outline some things to watch out for when writing
- It's also very useful to know How to Work with Conditional JavaScript Formulas and How to Work with JavaScript Arrays and Loops.
1. Gather the details about the issue
You will use these details and information to help in the troubleshooting steps below.
-
- What is the expected outcome and what's happening instead?
- Review the code and use comments to keep track of what each line of code should be doing so you know what to expect when testing to find the source of the problem. Or if you need to reach out to the Q Support team for help.
- Note any errors that come up, especially ones that mention what line of the code the error is occurring. Google any error messages to see what they might be caused by.
- If the error is not due to a particular function, see JavaScript Fundamentals for a reference on the correct syntax to use when using JavaScript in Displayr.
- Search the Q wiki for example code that does what you want. You may find this as example code or you may expand the JAVASCRIPT > Show code section of our built-in automations to see and compare its code with your own. You can also browse the individual sections below to see if there are examples that do something similar to what you're looking to do.
- JS functions - has general JS functions and libraries of functions (at the bottom of the page) written to work with specific items in your report.
- Built-in rules for tables and plots - at the bottom lists pages for each rule where you can access the underlying code and copy/modify bits of the code that you need for your custom code.
- List of functions and properties you can use with Rules on a table - and other functions and properties you can use with tables in a QScript.
- QScripts used in Built-in Automations - lists pages for each automation that uses a QScript where you can access the code to copy/modify bits of code.
- JS snippets - contains generic examples of how to do certain things to items/tables within your report.
- JS for variables - has generic code and scripts for creating and modifying JS variables within the tool.
- If the error occurs after a particular function, search for the function on the Q wiki with a single "(" afterward to try to find example code that uses the function as well as the reference of the function. Otherwise, if it is a generic JavaScript function, you can Google the function to find more information.
2. Find what is causing the issue
-
Check for syntax errors as explained in JavaScript Coding Tips and by copying your code into https://jshint.com/ (though this website may not be able to run custom functions created by Q). For QScripts and Rules, if you have a syntax error, it is likely the line or one of the lines in front of the one listed in the error message that pops up from the editor after you click Play:
- If there's an error message, review the internal documentation or any googled results you found about the error message to get clues as to what may be the problem and what might be the solution.
-
If the error message or issue is due to a specific function:
- Confirm the function is actually supposed to do what you expect it to do based on the documentation and code examples.
- Confirm the data and other inputs used by the function are what you expect it to use. If using a Rule or QScript, use
log()to print the data and other inputs to the console log that shows at the bottom/pop-up after the code runs (see Helpful Functions used to Troubleshoot below for more info). You'll see the -1s returned in the log below for the two inputs to the moveRowAfter() function. Since -1 isn't a row number in the table, this means the rowIndex() function couldn't find the row labeled Coke or Pepsi. - Confirm the arguments (settings) used in the function are all in the documentation of the function and that the values given to them are what they expect. For instance, are you giving a list of row names to an argument that expects TRUE/FALSE? In the example below, the error can be explained because the technical details of the table.moveRowAfter() function requires you to give it a number instead of a row header:
- If you've modified code from an article in our Help Center or the Q wiki, check that all the appropriate steps and requirements in that article were followed.
-
For JS variables
- Confirm the variables being used in the code. The variable names being used in the code are highlighted in the Expression box and the raw data values being used are in the Preview of results box.
- Confirm the different response combinations result in the value you expect. Click Check Code to run your code and populate the Preview of results box. You can check Collapse duplicate inputs to see the different unique combinations of responses across variables and what the final result is. The row headers are the rows in your data that have that combination of responses and you can review the N column to see how many respondents are being classified based on those specific responses:
-
Values of the categories in your variables are used unless you specifically use
Q.Label()around your variable name. - Remember that normally, the entire JavaScript code is run separately for each record, using only that record's data. If you need to access information on all records at once, check Access all data rows. This may also mean changing how your code works. See: How to Work with JavaScript Arrays and Loops.
- Confirm the arguments (settings) used in the function are all in the documentation of the function and that the values given to them are what they expect.
-
For Rules and QScripts, identify what is causing the error or what line the data starts to give unexpected results:
- Start from the line with the error or unexpected result and print the data and other inputs using
log()to print the data and other inputs to a log window that pops up after the code runs (see Helpful Functions used to Troubleshoot below for more info). For example, below it becomes more apparent that one of the issues with the code is that there isn't a row labeled Coke in the table: - Step through the code as needed, moving up the lines of code confirming variables/data used are what you expect until you reach the earliest line where the result is wrong/unexpected. This is the line where you should start testing to find a solution.
- Start from the line with the error or unexpected result and print the data and other inputs using
3. Figure out a workaround or a solution
If the steps above don't lead to an obvious solution, use what you've learned to work toward a solution beginning with the first line that creates the issue. Note, you may need to revisit 2. Find what is causing the issue if your solution to one issue uncovers or causes another.
- Is the thing that caused the issue required or can you work without it?
- Are there things with the syntax you can tweak to see if there's an undiagnosed syntax issue? Most commonly this would deal with adding/moving commas, "", (), {}, and [].
- Is there a different way of referencing the data you're trying to create?
- Is there a different function you can use to get the data you expect? Search in our Help center or google for more ideas.
- Can you get something close but adequate to what you ultimately need with a different process? Like hiding rows with small sample sizes using R code rather than with a Rule?
4. Contact Support
If you've worked through these steps and haven't figured out the issue or solution, please contact our support team at support@q-researchsoftware.com or by clicking on File > Share > Send to Q Support (Encrypted) from within your specific project in Q. While we cannot create or troubleshoot complex, custom JS code for users through support, we can try to help you at least identify the issue and point you to relevant resources that may help you get unstuck.
Helpful Functions used to Troubleshoot
The log() function is the most useful function to use to troubleshoot JS code. Note that JS variables do not have log() functionality though. You can use log() to print any information you want regarding the variables and data you are working with inside the code editor of your Rule/QScript. You can also separate different log statements by pure text, log("......."); , to make reading the log easier. Also note that, if working with complex items like tables, you may need to denote specifically what property of the item you'd like to see. See the list of functions and properties you can use with Rules on a table for a reference for the example below.
For example, there's an error with the last line 5 in the code below so I want to confirm information about the table. I try to print the table to the log to see it (line 2), but the only thing that is shown in the log is ModifyTableOutput because that is the class of the table:
I look through the different table properties I can review and one is rowLabels so I print that to the log instead and see that there isn't a row labeled Coke or Pepsi on my table: