User Input for Rules

This feature is new in Q 4.8.

Scripts for Rules usually contain these steps:

1. Check the requirements for the script are met.
2. Set up controls for user input.
3. Validate input.
4. Format the table.

A Short Example

This example rule allows the user to specify a minimum n statistic. Any cells that have a lower n are highlighted. It produces this form for the user:

// Check the requirements for the script are met.
table.requireNumericTable();

// Set up controls for user input.
form.setHeading("Highlight cells with low samples:");    // appears above input controls
var labelControl = form.newLabel("Minimum n:");
var minimumNControl = form.newNumberBox("minimumN");
form.setInputControls([labelControl, minimumNControl]);

var colorControl = form.newColorPicker("color");
form.setOutputControls([colorControl]);

// Validate input.
var minimumN = minimumNControl.requireValue();           // highlights input box if not entered
var highlightColor = colorControl.requireValue();
if (table.availableStatistics.indexOf('n') == -1)        // format ignored where n unavailable
    form.ruleNotApplicable("this format only applies to tables with the N statistic");
form.setSummary("Highlight where n < "+minimumN);        // text appears with format in manager
form.setOutputColor(highlightColor);                     // output colour shown in manager

// Format the table.
var n = table.get("n");
var min, max;
var cellColors = table.cellColors;
table.rowIndices(false).forEach(function (row) {         // false => skips NETs
    table.columnIndices(false).forEach(function (column) {
        if (n[row][column] < minimumN)
            cellColors[row][column] = highlightColor;
    });
});
table.cellColors = cellColors;

Check the Requirements for the Script Are Met

Your JavaScript code may need to make assumptions about the table of statistics it is formatting, such as:

• The data is numeric. Most scripts operate on numeric statistics and will have this requirement.

table.requireNumericTable();

• The rows and columns have not been modified by earlier rules. If your script wants to calculate extra statistics for the original rows and columns (via calculateTable()), and interleave those statistics back into the same rows and columns, it needs to ensure an earlier script has not deleted or moved the rows and columns from their original positions.

table.requireOriginalRowsColumns();

• The statistics have not been modified by earlier rules. For example, if your script needs to calculate a sum of the averages on the table, it will not work correctly if an earlier script changes the Average statistic for own purposes, such as for storing a new novel statistic.

table.requireOriginalCellStatistics(null);

If the requirement is not met, then the script will be aborted and the user will see a warning. Subsequent rules will continue to run.

Set Up Controls for User Input

When running as a rule, your JavaScript code will have access to a form variable, which is a RuleForm object.

• Set the heading that appears at the top of the form using form.setHeading().
• Each control you want the user to see must be created by a call like (for example) form.newNumberBox(). All controls must have unique names, except for labels, which have no names.
• Specify the order you want for your controls by passing them in an array to form.setInputControls() (for the top section) or form.setOutputControls() (for the section labeled "Preview:"). Controls will not appear unless passed to one of these functions.

Validate Input

This goes after all controls have been set up so that all the controls will be visible if validation fails.

• Most validation is performed for you when you call control.requireValue(), but you can add any check you like and then call form.controlInvalid() if the user's input is not valid. Use control.getValue() to retrieve the value of a control where entry is optional.
• If your format does not apply to the table it is being run on then call form.ruleNotApplicable(). This will allow your rule to be applied to an entire project without causing errors where it does not make sense.
• Call form.setSummary() with a string that describes the format, according to the user's input. This is shown in the Rules tab, and makes it easier for the user to work out which rule is which. If your code highlights using color then also call form.setOutputColor() to make the color appear in the Format column.
• Call table.requireNumericTable() if your script will not work on text tables.

Format the Table

As per Table JavaScript and Plot JavaScript.

See also

• Rule Online Library