Using JavaScript to Modify Tables and Charts

In general, the easiest way to use JavaScript to modify a table or chart is via Rules. You should read that page prior to reading this page.

Refer to:

• Table JavaScript and Plot JavaScript Examples Library for examples.
• Table JavaScript and Plot JavaScript Reference for technical details.
• In Q 4.8 and later, rules can take input from the user.
• Caveats for Table JavaScript for important notes on how Table JavaScript affects the display of significance results.
• JavaScript for a more general discussion of how the JavaScript programming language works.
• QScript for tools for setting up projects using JavaScript.
• JavaScript Variables for detail on how to create new variables in the Variables and Questions tab using JavaScript.

Adding JavaScript to tables and charts

JavaScript is applied to tables and charts through the use of Custom Rules. To add a new custom rule to a table or chart select Automate > Custom Rule > Edit JavaScript. To modify the JavaScript in an existing rule, select the Rules tab under the table (or use Automate > Manage Rules), select the rule that you want to change, and then click Edit Rule and Edit JavaScript.

To make use of JavaScript from a Rule in the Online Library in your own JavaScript, see Customizing Rules.

You can either directly type into the large box or cut and paste from another application. If you are writing a lot of JavaScript it may be useful to use a special-purpose JavaScript text editor (e.g., see Setting Up a Text Editor for QScript).

Table Calculation Process

The JavaScript runs at the end of the process of calculating a table or chart and generating the output. The process for charts is similar to tables - in the background, Q is actually generating a table to construct the data to chart, including the series labels.

Manipulations of data done using Table JavaScript and Plot JavaScript can be very different to the consequences when changing the data elsewhere. For example, if you apply a filter to a table using Table JavaScript it will not automatically be applied in the the statistics shown below and to the right of the table; to change these requires additional code.

The process is as follows:

1. The main table output is generated, which incorporates:
   1. statistics selected by using the table context menu
   2. any changes to the row or column question's categories, including re-ordering, renaming, merging, etc. - any operation done via the table context menu
   3. cell color shading done via the table toolbar buttons
2. If there are any Statistics - Right selected, another table output is generated for the table on the right, which is merged with the main table output later.
3. If there are any Statistics - Below selected, another table output is generated for the table below, which is merged with the main table output later.
4. If Hide Empty Rows/Columns is ticked, empty rows/columns (with all missing data or all zeros) are removed from the table.
5. The multiple comparison correction is performed, generating the Corrected p and Multiple Comparison Adjustment statistics (which affect displays of significance).
6. Cell significance is calculated, determining arrow length and font color.
7. The sample size description (shown in the table's footer) is calculated from the table's cell statistics (n, Base n, etc.).
8. The JavaScript is run, given the default table outputs:

   Input	Description
   table	The main table output, from step 1.
   right_table	The table output for Statistics - Right, from step 2.
   below_table	The table output for Statistics - Below, from step 3.
   current_item	Q4.11: The table or plot object.

9. The same table outputs which were given to your JavaScript, and modified by your JavaScript, are used to display on the screen, or exported to PDF/Office.

Plot JavaScript

Q's charts perform table calculations to generate the statistics and category labels shown on charts. These table calculations are generated through the same Table Calculation Process described above. Thus when writing JavaScript for a chart it is necessary to consider the table, or in some cases multiple tables, that have been used to create the chart. This process introduces limitations on what can be done with JavaScript on charts. The table below gives a summary of the properties that can be manipulated for each chart type.

The JavaScript used in a Custom Rule can determine if it is being applied to a table using the property table.forPlot, but it is not possible for the JavaScript to determine the chart type that is selected.

Bar, Line, and Stacked Charts

The following chart types are the easiest to manipulate with JavaScript:

• Bar/Column/Line charts
• Stacked column/bar charts
• Grid of bars charts

These chart types use data from a single table, and you can determine the table by looking at the Blue and Brown drop-down menus and considering the table that is created by these selections. You can switch back to the table in the Show Data As menu if you need to check the layout of the underlying table. Note that this underlying table does not change it orientation when you change the orientation of the plot, for example changing from Columns to Bars, or from horizontal lines to vertical lines.

Complicated Chart Types

Some types of charts are generated by computing a number of tables behind-the-scenes in order to obtain the data for the chart. This introduces additional limitations for the application of custom rules on these charts. These chart types are:

• Column Chart with Trend
• Trend Plot
• Scatterplots

The JavaScript in the rule will run for each table that is used to generate the chart. For example, the Column Chart with Trend generates one table for the spark lines and a second table for the columns, and so the JavaScript in a custom rule will run twice. It is important to note that any JavaScript must be compatible with all of the tables that are calculated during the creation of a chart.

It is generally best to avoid using JavaScript to manipulate charts of these types, or to restrict changes to to labels and footnotes as shown in the table above.

Worked examples

The following examples from Table JavaScript and Plot JavaScript Examples Library contain additional documentation and, if read in order, provide a basic level of training in how to modify tables and plots using JavaScript:

• Making One Row Appear After Another
• Color Bars That Belong To a Specific Category (e.g. Product)
• Computations - Adding Average Rows to Tables Containing Spans
• Filtering Rows in a Grid
• Blanking Cells With Small Sample Sizes
• Sorting Tables By the Largest Column

Buttons, Options and Fields

Check Code Runs the JavaScript code and reports whether an error occurred.

Disable JavaScript When ticked, this prevents the JavaScript code from running, and allows you to temporarily view the original Table/Chart output. This is helpful for diagnosing errors in your JavaScript.