The formal description of the «Rule()» command is found in The Rule Command article.
Suppose you have a need to capture a number which is between a maximum and minimum value, but must be an integer value, i.e. have no fractional part. The IsNumber validation function permits specifying a maximum and minimum value but does not restrict the value to an integer, and the IsDigits function does not permit specifying a maximum or minimum value (and in addition does not permit an optional + or – sign). The solution to this problem is to chain together two Rules:
«Rule(NumberOfPets,hard,IsNumber,1,10,"You must have at least one pet but not more than 10")»«Rule(NumberOfPets,hard,not(contains(NumberOfPets,'.')), "there is no such thing as part of a pet")»
If the NumberOfPets field fails either of these rules, then the messages of both rules are issued, joined by a comma. In other words, the message would read “You must have at least one pet but not more than 10, there is no such thing as part of a pet”.
The article Data capture interview layout tips discusses how commands such as Caption, Heading, Help, etc. can be placed in a template to be included into a set of templates (a “layout” template). If a data element is referenced in the layout template by a «Caption()» command, for example, but is not referenced in a specific including template, then the «Caption()» command is ignored. The same applies to the «Rule()» command.
This means that if you have a number of related templates that use the same data elements, then the validation rules need only be specified in the layout template that is Included into the other templates. If a specific including template does not refer to a data element that has a Rule defined for it, then that Rule is ignored.
Softening a Hard Rule
This feature can be used in conjunction with chaining to achieve various effects. For example, suppose that there is a rule
«Rule(IDNumber,hard,IsZaIdnumber,"The IDNumber field is not a valid South African ID Number")» in the layout template (the template that is Included into all the others). But, there is a specific template, say “Affidavit in Respect of An Invalid Identity Number” which requires that the user be able to capture an ID Number that does not conform to the rules. On that specific template, the template author could code the following Rule:
«Rule(IDNumber,soft,1 = 1,"but do you want to accept it anyway?")»
This rule is then chained onto the existing rule (assuming the layout template is Included at the start of the including template), with some interesting effects. The first is that when Rules are chained, the hardness of the last rule in the chain takes effect. In this case, the two chained rules become one rule which is “soft”. Then, notice that the condition part of the second Rule is not a system validation function, and so it is evaluated like the condition in an «If» command. The condition 1 = 1 is always true, so that if the first rule validates (i.e. the IDNumber is in a valid form) then the combination will validate. But if the first rule does not validate, then the result is a “soft” failure, which results in the user being shown the message “The IDNumber field is not a valid South African ID Number, but do you want to accept it anyway?”, and at the same time the user is given the choice of pressing a “Yes” button or a “No” button.
When encountering The FormatNumber Function in a template, XpressDox will insert a Rule command automatically for the referenced data element. This is a “hard” rule. This automatic hard rule can be softened using the technique outlined above.
Note that the softening Rule command must appear after the FormatNumber in the template in order to take effect.