How to Create a QScript to Insert a Custom Rule

This article describes how to convert your custom Rule into a QScript that allows you to apply the Rule to all selected tables. This can be particularly useful when you wish to re-use a custom Rule in different documents and are providing it for non-technical users. The benefit of using a QScript to insert a rule is that it avoids the necessity to cut and paste code.

Requirements

A Displayr Enterprise user license, which includes the ability to add custom analysis menu items.
You should first create your custom rule according to the steps outlined in How to Create a Custom Rule. Here, we will use the same example to display the top-specified rows of a table using the following code:

includeWeb("Table JavaScript Utility Functions");
// Create the form
form.setHeading('Select the number of rows to show on a table');
// Create the phrase 'Number of rows:'
var label_statistic = form.newLabel('Number of rows:');
// Create a control where a user can enter a number. 
var numeric_up_down = form.newNumericUpDown('threshold');
// Specify the default number of rows to be shown 
numeric_up_down.setDefault(5);
// Specify that the user must enter whole numbers. 
numeric_up_down.setIncrement(1);
// Prevent the user from having tables with less than 1 row 
numeric_up_down.setMinimum(1);
// Tell Displayr to create the form with the declared label and control
form.setInputControls([label_statistic, numeric_up_down]);
var maximum_number_rows = numeric_up_down.getValue();
// Create the form title by referring to chosen value
form.setSummary('Top ' + maximum_number_rows + ' rows');
// Delete the rows
while(table.numberRows > maximum_number_rows) {
table.deleteRow(table.numberRows - 1)
}

Method

Once you have created your custom rule, there are several main steps:

To open the QScript editor, right-click or click '+' in the Report tree, and select Calculation > QScript > New.
Format your custom rule as a string.
Create the QScript to add the rule to your document.

Format your rule as a string

The code for the rule needs to be added as a string within the code for the QScript. This means that the entire block of code must be placed within backticks ` `. The properly formatted string to use for the example code above is as follows:

var rule_expression = `includeWeb('Table JavaScript Utility Functions');
// Create the form
form.setHeading('Select the number of rows to show on a table');
// Create the phrase 'Number of rows:'
var label_statistic = form.newLabel('Number of rows:');
// Create a control where a user can enter a number.
var numeric_up_down = form.newNumericUpDown('threshold');
// Specify the default number of rows to be shown
numeric_up_down.setDefault(5);
// Specify that the user must enter whole numbers.
numeric_up_down.setIncrement(1);
// Prevent the user from having tables with less than 1 row
numeric_up_down.setMinimum(1);
// Tell Displayr to create the form with the declared label and control
form.setInputControls([label_statistic, numeric_up_down]);
var maximum_number_rows = numeric_up_down.getValue();
// Create the form title by referring to chosen value
form.setSummary('Top ' + maximum_number_rows + ' rows');
// Delete the rows
while(table.numberRows > maximum_number_rows) {
table.deleteRow(table.numberRows - 1)
}`;

In this code:

The code has been assigned to a JavaScript variable called rule_expression.
The block of code is enclosed in backticks ` ` to denote a template literal string.
The last line of the string is ended with a ; to indicate the end of the instruction (just like any other line of JavaScript).

Create the QScript to add the rule

The QScript for adding the rule needs to do two things:

It needs to create a new rule object in the document. This is done using the QScript function called newCustomRule().
It needs to add the rule to at least one table. The best approach to satisfy this requirement is to apply the rule to any tables that the user has selected before they run the script, and these tables are obtained using the function selectedItems().

The QScript below will add the rule to every table that is selected at the time the script is run:

var rule_expression = `includeWeb('Table JavaScript Utility Functions');
// Create the form
form.setHeading('Select the number of rows to show on a table');
// Create the phrase 'Number of rows:'
var label_statistic = form.newLabel('Number of rows:');
// Create a control where a user can enter a number.
var numeric_up_down = form.newNumericUpDown('threshold');
// Specify the default number of rows to be shown
numeric_up_down.setDefault(5);
// Specify that the user must enter whole numbers.
numeric_up_down.setIncrement(1);
// Prevent the user from having tables with less than 1 row
numeric_up_down.setMinimum(1);
// Tell Displayr to create the form with the declared label and control
form.setInputControls([label_statistic, numeric_up_down]);
var maximum_number_rows = numeric_up_down.getValue();
// Create the form title by referring to chosen value
form.setSummary('Top ' + maximum_number_rows + ' rows');
// Delete the rows
while(table.numberRows > maximum_number_rows) {
table.deleteRow(table.numberRows - 1)
}`;

// Make the rule available in the project
var new_rule = project.rules.newCustomRule(rule_expression, {});

// Get the array of items that the user has selected before they run the script
var selected_items = project.report.selectedItems();

// Apply the rule to each selected item
selected_items.forEach(function (table) {
    table.rules.add(new_rule);
});

// Keep current items selected
project.report.setSelectedRaw(selected_items);

In this code:

The expression for the rule needs to be defined above the rest of the code, which then adds the rule to the document.
The rule must be added to the set of rules in the project before it can be added to any tables. This is achieved by referencing rule_expression within project.rules.newCustomRule(), where the resulting rule is stored in the object called new_rule.
The tables that have been selected by the user at the time the script was run are stored in an array called selected_items.
The function forEach is used to loop over the array selected_items and perform the same action on each item in the array. In this case, the function inside forEach uses table.rules.add() to add the custom rule called new_rule to the table.

Save and run your QScript

Once you have entered your code, press OK.
Enter a name for the script to be saved to your Displayr Cloud Drive.
Right-click or click '+' in the Report tree, and select Calculation > QScript and choose your QScript.

How to Create a Custom Rule

How to Create a Custom QScript

How to Use QScripts in Displayr

JavaScript Fundamentals