Using and storing variables

Variables in XpressDox templates

The concept of variables in XpressDox enables the results of calculations to be stored for further use in the template, and even for future templates.
Here are some examples to illustrate this, assuming a data set which looks like:

<xml>
  <librarianName>Mrs. J. Bloggs</librarianName>
  <book>
    <title>Harry Potter</title>
    <author>J.K. Rowling</author>
    <costPrice>200</costPrice>
  </book>
  <book>
    <title>Carrie</title>
    <author>Stephen King</author>
    <costPrice>150</costPrice>
  </book>
</xml>

Setting and getting a simple variable

«SetV(‘TotalCost’,sum(book/costPrice))» creates a variable named ‘TotalCost’ with a value of 350.

«GetV(‘TotalCost’)» inserts the value of the ‘TotalCost’ variable into the document.

Neither of those variables will be inserted into the data set. However, using CreateDataElement a new data element can be created from the variable you just set.

«CreateDataElement(‘TotalCost’,’totalCost’)» creates a data element named ‘totalCost’ as a direct descendant of the root element with the value of the ‘TotalCost’ variable. This only happens after the full template merge has completed, so the new data element will not be available in the template in which it is created.

A repeated variable

«ForEach(book)»
«SetV(‘SellingPrice’,costPrice * 1.5)»

Cost Price: «FormatNumber(costPrice,'#!,##0.00')»
Selling Price: «FormatNumber(GetV(‘SellingPrice’),'#!,##0.00')»

«CreateDataElement(‘SellingPrice’,concat(‘book[‘,position(),’]/sellingPrice’))»
«End(forEach)»

At the end of the above two examples, the XML data set would look like this:

<xml>
  <librarianName>Mrs. J. Bloggs</librarianName>
  <book>
    <title>Harry Potter</title>
    <author>J.K. Rowling</author>
    <costPrice>200</costPrice>
    <sellingPrice>300</sellingPrice>
  </book>
  <book>
    <title>Carrie</title>
    <author>Stephen King</author>
    <costPrice>150</costPrice>
    <sellingPrice>225</sellingPrice>
  </book>
  <totalCost>350</totalCost>
</xml>

GetVn

With Version 4 of XpressDox, the function «GetVn()» was introduced – it is needed in situations where the value of a variable is known to be numeric and is required as such by the particular command being used.  Examples would be «substring(FirstNames,GetVn(‘count’),1)» or «Party[GetVn(‘Counter’)]/Name».

The ToNumber function will perform a service similar to that of GetVn, as the following is equivalent to the above:
«Party[ToNumber(GetV(‘Counter’))]/Name».

SetVr

Often a SetV function is used but the template author wants the paragraph in which it is used to be removed.  The RemoveParagraph function can be used for this, but the SetVr function provides a shorthand way of performing the SetV and then removing the paragraph.

Note that CreateDataElement used to be known as SaveV. SaveV is still available for backward compatibility, but will not be found in the Command Assistant list.

GetVOrDefault

In the case where you access variable with a GetV, and that variable had not yet been created by a SetV, this will result in XpressDox issuing an error message. But sometimes, in a particularly complex set of templates, as a template author you might not be sure that a variable will have been created and allocated a value. In this case you could use the GetVOrDefault function.

An example:

«RepeatWhile(GetVOrDefault('Number',0) > 0)»
some text and fillpoints
«IncrementV('Number',-1)»
«End()»

The above code inside the RepeatWhile would set the variable Number to 0 if it had not already been assigned a value, or else it would use the value assigned, and then output “some text and fillpoints” as many times as the value of the variable. In other words, if the variable had not been assigned a value, the “some text and fillpoints” would not be output at all (because the variable will be assigned the value of 0 by the function).

The GetVOrDefault function was introduced with version 9.0.0 of XpressDox, and in version 11.0.0, this functionality was subsumed into GetV – i.e. GetV(‘Number’, 0) will function in the same way as GetVOrDefault(‘Number’,0)

Shortcuts

With effect from Version 7, there are a number of shortcuts for referring to some of the variable-handling functions. They were introduced to take away the amount of typing necessary when many variables are being used.

For example, «SetVr(‘This’,That)» can now be written «::RThis,That» which saves typing a set of quotes and a set of parentheses.

Similarly, «SetVr(‘This’,GetV(‘That’))» can be written as «::RThis,::Gthat».

A full list of the shortcuts is as follows:

::A - AppendVr
::G - GetV
::I - IncrementV
::N - GetVn
::P - RemoveParagraph
::S - SetV
::R - SetVr

The shortcuts are translated early on in the parsing process into their formal format, so that sometimes if there are other syntax errors relating to the shortcut usage, the error message will refer, for example, to “GetV” rather than “::G”.