How to Add Table Validations to Rules

This article describes how to add table validations to custom Rules.

Requirements

• A table with a custom Rule applied.
• This article assumes you are already in the New custom rule (write your own JavaScript) > Edit JavaScript Rule view specified in How to Create a Custom Rule.
• You have read How to Create a Custom Rule and How to Access Statistics from a Table in a Rule.

Please note this requires the Data Stories module or a Displayr license.

Method 1 - Check table requirements

Table requirement validations should be placed at the top of your code as follows:

table.requireNumericTable();

The above function will check whether the table has numeric values. If it is a raw text table then it will return a not applicable message when applying the rule and abort the script: 

The alert will also be visible in the Apperance > Rules tab view when you hover over the rule in question.

Other require functions include:

table.requireOriginalRowsColumns();

This function checks that the rows and columns have not been modified by earlier rules. If a previous rule has deleted or moved the rows and columns from their original positions, this will ensure there won't be any issues that could affect the re-placement of statistics via code.

table.requireOriginalCellStatistics(null);

This function checks that the statistics have not been modified by earlier rules. This is applicable when you change the values for a statistic in a previous rule but the current rule requires the original values.

Method 2 - form.ruleNotApplicable()

This validation method allows for custom messaging and again should be placed towards the top of your code.

The below example uses the availableStatistics function to see if Column % is an available statistic in this table: 

var stat = "Column %";
if (table.availableStatistics.indexOf(stat) == -1)
  form.ruleNotApplicable(stat + " is not available on this table");

If it is not available, then the form.ruleNotApplicable function will display a specified message in the form dialog when applying the rule.

The alert will also be visible in the Apperance > Rules tab view when you hover over the rule in question.

Method 3 - Suppress output

A further validation method is to replace the contents of your output with a specified message, for example, when a condition is met:

table.suppressOutput('Not applicable');

This will be previewed on the Edit formatting rule screen:

And it will be returned in place of your table or chart as a text message:

Note, this also replaces the underlying data when exporting.

Next

How to Reference and Calculate Tables in a Rule

Later

How to Add Table Spans Using a Rule

How to Add a Custom Table Footnote

How to Custom Sort Tables

See Also

How to Use Rules in Displayr

How to Customize a Rule

How to Create a Custom Rule