Using and storing variables

by Peter on September 30, 2009

in User Reference

This concept 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, getting and saving 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.

<<SaveV(‘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)>>

<<SaveV(‘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>>.

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 the SaveV function has been replaced by the CreateDataElement function. SaveV is still available for backward compatibility, but will not be found in the Command Editor 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.

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
::N - GetVn
::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”.