Introduction
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.
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 Properties > 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 for 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 Properties > 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
See Also