Creating a Custom Rule

Although many rules are already available either by selecting them from the Automate menu or the Online Library, sometimes it can be useful to create a completely new rule from scratch.

Steps for creating a custom rule

1. Select the table(s) or chart(s) that you wish to modify using the rule.
2. Select Automate > Custom Rule > Edit JavaScript.
3. Enter the desired JavaScript code (the box currently contains instructions, and these can be overwritten or left in-place). You can create forms, as is shown in the second worked example below, and refer to data in Q if required (see Table JavaScript and Plot JavaScript for more information).
4. Press Close, Yes and OK.

Re-applying the custom rule elsewhere

Once a Rule has been created, you can reapply it to other tables and charts in the same project using the Rules tab. To apply it to another project, you can:

1. Repeat steps described above, cutting and pasting the code from one project to another.
2. Add it to the Project Templates.
3. Request that we add your rule to the Online Library, so that it is available to all users.
4. Create a QScript which adds the rule to a project, and then run this QScript using Automate > Run QScript (Macro) from file. This is generally only worthwhile doing if there is a need to non-technical people to easily apply the rule to new projects. For instructions on how this is done, see How To Create a QScript To Insert a Custom Rule

Worked example 1: Showing only the top 5 rows on a table

If you follow the steps above, and paste in the following code, any tables or charts that have this rule will only show the top 5 rows (or fewer if the table has less than 5 rows).

while(table.numberRows > 5) {
  table.deleteRow(table.numberRows - 1)
}

A few things to note about this:

• while is a standard term in programming (see JavaScript Tips for other standard terms). If the bit in the parentheses (i.e., table.numberRows > 5) is true, then whatever follows in the braces (i.e., table.deleteRow(table.numberRows - 1) is repeated again and again until the bit in the parentheses is not true. Thus, while the number of rows is greater than 5, rows will continue to be deleted.
• table.numberRows computes the number of rows in the table. When you are entering your code, you will see a list of Common Methods shown on the right side of the screen. Alternatively, you can read Table JavaScript and Plot JavaScript or contact support for assistance in figuring out which bits of Table JavaScript and Plot JavaScript do what.
• table.deleteRow(table.numberRows - 1) dells Q to delete the last row of the table. For example, if there are 10 rows in the table, then table.numberRows - 1 equal 9 and thus the instruction is to delete row 9. If you are new to programming, the surprising bit of this will be that the last table on the row is 9. This is because by convention in most advanced programming languages, the first row of a table is row 0, the second row is row 1, etc.

When you create this rule, it will appear in the Rules tab as Custom Table JavaScript. It is generally a good idea to give it a better name, as is done if we instead use the following code:

form.setSummary('Top 5 rows');
while(table.numberRows > 5) {
  table.deleteRow(table.numberRows - 1)
}

Worked example 2: Allowing the user to control the number of rows shown on a table

This example builds upon the first example, by creating a way for a user to easily modify the number of rows shown on the Rules tab, without the need to write any code (after the rule has been created).

// creating the form
form.setHeading('Selecting the number of rows to show on a table');
var label_statistic = form.newLabel('Number of rows:'); //creating the phrase 'Number of rows:' 
var numeric_up_down  = form.newNumericUpDown('threshold'); //creating a control where a user can enter a number.
numeric_up_down.setDefault(5); // specifying the default number of rows to be shown
numeric_up_down.setIncrement(1); // specifying that the user must enter whole numbers.
numeric_up_down.setMinimum(1); // preventing the user from having tables with less than 1 row
form.setInputControls([label_statistic, numeric_up_down]); // telling Q to create the form
// Extracting the number of rows provided by the user and assigning it to a variable.
var maximum_number_rows = numeric_up_down.getValue();
// Deleting the rows.
while(table.numberRows > maximum_number_rows) {
  table.deleteRow(table.numberRows - 1)
}
// creating the form title
form.setSummary('Top ' + maximum_number_rows + ' rows');

Note that the comments explaining the code are shown in the code itself (i.e., Anything that follows a // is ignored by Q when it follows the instructions in the code). It is always a good idea to add lots of comments, as what seems obvious at the time you write the code can be hard for you and others to understand at a later time.

A third, even more complex example, which builds on the ones above, is Modify Whole Table or Plot - Show Only Top K and Specified Rows.

Common customizations

In some situations, a rule will have a set of options that you can easily modify, as follows:

1. Press on the Rules tab (bottom-left of the table/chart).
2. Select the rule that you wish to modify.
3. Press Edit Rule and make the desired changes.