People are often tempted to use the term “variable” for what XpressDox refers to as a data element. The distinction is an easy one: a data element has a constant value throughout the template’s lifetime – the value can only be changed when the user next gets a chance at it in the data capture interview, otherwise, once it’s captured, that’s its value.
XpressDox does, however, support the concept of variables: i.e. those data items whose value can change while the data are being merged into the template. This recipe will expose some of that functionality.
The first paragraph is not strictly true any longer, now that The OnExitSet and OnEnterSet Commands have been introduced. What remains true, though, is that XpressDox variables cannot be used outside of assembling the document – i.e. they are only available after the “OK” button on the interview has been pressed, and while the document is being assembled.
Already in the Performing calculations recipe we have a need for a variable – an item whose value is going to change as the template gets run. This is in order to calculate the totals on the invoice template. The snippet to do this would be:
«SetV(“Total”,0)»
Product
Quantity
Unit cost
Total
Total inc. Tax @ 14%
«ForEach(Transaction)»
«Product»
«SetV(“TranCost”,UnitCost * Qty)»
«SetV(“TranCostPlusTax”,
GetV(“TranCost”)
* 1.14)»
«IncrementV(“Total”,
GetV(“TranCostPlusTax”))»«Qty»«UnitCost»«GetV(“TranCost”)»«FormatNumber(
GetV(“TranCostPlusTax”))»
«End(foreach)»Total «FormatNumber(
GetV(“Total”))»
Here the extended cost (“unit cost times quantity”) is also calculated and saved in a variable (variable TranCost). This variable’s value is then multiplied by 1.14 to get the Tax inclusive amount (TranCostPlusTax), and this Tax inclusive amount added to the running total, i.e. the variable Total. This addition is done by the IncrementV function.
The SetV function sets the value of a variable, and GetV gets and returns the value of a variable.
Notice that the result of GetV can be inserted directly into the merged document, as in «GetV(“TranCost”)», or it can be passed as a value to a formatting function, as in «FormatNumber(GetV(“Total”))».
Note also that variable names are ALWAYS enclosed in quotes.
Further definitions are contained in the User reference article on using and storing variables.
The SetVR function
You will notice that the SetV function can sometimes cause an extra empty paragraph to appear in the merged document. This extra paragraph can be removed using the «RemoveParagraph()» command.
But the SetVR function has been introduced to relieve the burden of attaching «RemoveParagraph()» to so many «SetV()» functions. SetVR functions exactly like SetV, but in addition causes the paragraph in which it appears to be removed from the merged document.
