Arithmetic in XpressDox
Arithmetic in XpressDox
Because XpressDox uses XSLT as its document automation engine, the arithmetic features of XSLT are all available to template authors.
There is a caveat, though, and that is that XSLT requires that all number presented to it in calculations must be in a specific format. The specific format is that the numbers must be only decimal digits and possibly a decimal point (period) – “.” – signifying the fractional part.
Examples of valid XSLT numbers are:
Notice that there is no “thousands separator” character. In other words 1,234.56 is NOT a valid number to XSLT and if you tried to include it in a calculation you would be likely to get a result of “NaN” (which, in XSLT speak, means “Not a Number”). Sometimes XpressDox will render NaN as a zero.
This is not too much of a problem in places like the USA, Canada and the UK, where people are used to entering numbers with full stops (periods) as decimal points, whereas in other regions, where the number format is different, it can be a great hinderance. On top of that, no matter where you are, you shouldn’t be entering numbers with thousands separators.
The old days
XpressDox tried to cater for that situation by providing the Rules IsRegionalNumber and IsNumber to try to empower the template author to make sure that numbers captured by users came into the data set in a known format. In addition, the «
RenderAsNumeric()» function, and also the «RegionToX()» and «
XToRegion()» functions helped to get numbers ready for calculations, and, once calculated, get the answers back into “regional” format for use in functions such as FormatNumber. While these functions perform their duties well, it is nonetheless a burden on the template author to keep remembering what format the numbers are in and how to manipulate them correctly.
The answer : XSLT Format
There is a command which the template author can put into every template, viz. «
ExpectXSLTFormatNumbers(Yes)», which tells the XpressDox assembly engine that it can now expect that all numbers presented to it will be in XSLT-compliant format. This applies to numbers sourced from data sources (but not text files) as well as to numbers entered in the interview.
While the application of the command will be automatic when data are retrieved from data sources, there is a little bit of work to be done by the template author for other data elements entered in the interview.
XpressDox is able to infer a number of things from the context of a data element what its format should be. For example, if there is a command «
FormatNumber(Amount)» (or, for example «
floor(Amount)») then XpressDox will know that the data element Amount must be stored as XSLT format in the data set.
But if a data element appears for example in a calculation, then currently XpressDox is unable to determine that the data element should be numeric. In this case, use the command «
CaptureDataElements(Amount,Price,Discount,Decimal)» is also possible.
Applying the new features
If there were any advice to be given to a template author on whether to use «
ExpectXSLTFormatNumbers(Yes)», the answer would be, yes, definitely. Especially for new sets of templates.
This advice can not apply in general to existing template sets in that the datasets saved for the templates might not have good XSLT format numbers.
If you are about to embark on a new set of template construction, the rather than trying to work out a mechanism of applying «
ExpectXSLTFormatNumbers(Yes)» to all templates, there is a feature in the configuration which enables the template author to set this for all templates in a specific folder, and its sub-folders.
Some tricky situations
One of the mechanisms that XpressDox uses to ensure that users capture numbers in the correct format is to generate a Rule command for the data element(s) in question.
For example, when XpressDox encounters «
FormatNumber(Amount)», it will generate the following:
1. When ExpectXSLTFormatNumbers is Yes:
Rule(Amount,hard,IsNumber,,,'The value must be a validly formatted number')»
2. When the ExpectXSLTFormatNumbers is No or not set:
Rule(Amount,hard,IsRegionalNumber,,,'The value must be a validly formatted number')»
The “tricky situation” is that, suppose you want to apply a further Rule to Amount to make sure that it is greater than 1000, for example. This Rule would be
Rule(Amount,hard,(Amount > 1000),,,'The Amount must be at least 1000.')»
In order for this second Rule to chain onto the first one, it would have to be included in the template after the «
FormatNumber(Amount)». This might be OK, but is counter-intuitive if your desire was to define all the data elements with captions, rules, headings, footings, etc ., in a separate template.
XpressDox can help you to accommodate that situation by use of the command «
InhibitAutomaticRuleOnNumberFunctions(Yes)». When this command is in operation, the automatic Rule described above will NOT be generated. This would mean, though, that you should generate your own Rule to enforce the format, for example:
Rule(Amount,hard,(IsNumber(Amount) and Amount > 1000),,,'The Amount must a validly formatted number whose value is at least 1000.')»
Numeric data in the Interview
All of the above discussion has been about how to get nicely formatted numbers into the data set. We can now ensure that all numeric data are stored in the data set as XSLT format.
But this does not mean that users capturing numbers into the interview must be forced to enter the numbers in XSLT format. In English regions, users might want to enter the thousands separators, e.g. the number One Thousand Two Hundred and Thirty Four Point Five Six as 1,234.56. And users in Germany, for instance, would like to enter the same number as 1.234,56.
XpressDox is quite flexible in how it will permit users to enter the numbers.
XpressDox Desktop (in Word)
The input format for numbers is governed by the menu item Interview Number Format in the XpressDox Ribbon, under the main Settings menu. The Interview Number Format has two values, the default being “Windows”. “Windows” means the settings as defined in the Region in the Windows Control Panel. The other option for Interview Number Format is “User Chosen Language”. This means that the format defined for the language chosen in the Language Ribbon option.
These options permit a number of scenarios. Here are some examples:
- An English speaking user in the USA with an English language edition of MS Word could leave their settings at the default. They would then be able to enter numeric information in the “English” format with or without thousands separators.
- An English speaking user in Switzerland, using a computer whose Region settings in the Control Panel is “de-CH” could nonetheless choose the Language in the XpressDox Ribbon as English-US or English-UK, and the Interview Number Format as “User Chosen Language” and so be able to continue entering numeric data in the format to which they are accustomed.
- A Hungarian speaker, who cannot speak any of the languages supported by the XpressDox interview, but nonetheless can get by with a German language interview, can select the German language option, and the Windows Interview Number Format. Then, as long as their Windows Region has the “Hungarian” option, they will be able to enter their numbers with a space as a thousands separator and the comma as the decimal point.
Regardless of the format for input and the format in the data set, numbers formatted with «FormatNumber()» will, by default, be output in the format determined by the Windows Region settings.
The FormatNumber function does, however, have the option for the template author to specify a format, for example «
FormatNumber(Amount,'','CH')» will cause the number 1234.56 (XSLT format) to be output as 1’234.56. XpressDox pre-defines these output codes as
CH: “Swiss” format, as in the example above.
CX: 1 234.56
FR: 1 234,56
US – same as EN
ZA – same as FR
In the case of a number format not covered by these codes, any of the codes described in Table of Language Culture Names, Codes, and ISO Values can be used, for example “kok-IN” (Konkani- India) which will output 1234567.89 (XSLT) as 12,34,567.89.
Please note that the arithmetic features described in this Cookbook article are available from Version 9.0 of XpressDox. You will need to download and install that version, and also make sure that your licence is valid for at least version 8.1.