DocFlex generator maintains user variables that can be assigned and accessed within FlexQuery expressions in templates.
Each user variable is associated with a certain context,
in which it is identified by a unique case sensitive name.
The variable holds a value, which may be any object or null
.
The variable context (or scope) may be one of three types, which determines how long a variable is maintained and where it can be accessed:
Note: the same template can call itself (directly or indirectly). In that case, this will be a different processing of that template and, therefore, a different variable scope.
Note: the same stock-section can call itself (directly or indirectly). In that case, each call represents a different scope of user variable.
Any user variable can be created only using setVar()
function,
which also allows changing the value of an existing variable.
The variable value can be obtained using setVar()
function.
To check if a variable with some name exists in a given context,
use checkVar()
function.
You can also remove the variable from the scope
using removeVar()
function.
The traceVars()
function allows you to trace the state of all
user variables associated with the given context or a subset of them.
Please note, we do not encourage particularly using of user variables (especially, to control the processing of template components) because this will make your templates difficult to understand and debug as well as may cause various side effects. So, it is better to avoid involving user variables whenever possible!
However, for certain tasks, user variables may be the only means.
Example:
Accumulating Total Sums
Suppose, you need to accumulate a total sum of numbers obtained from values of
attributes with the name "PRICE"
contained in elements
that are iterated by a certain Element Iterator.
Here is how you can do this using a user variable.
In the iterator's Init Expression (see Processing | Init/Step/Finish tab in the
iterator's properties dialog) create a variable with the name "TOTAL"
and the initial value set to 0:
setVar("TOTAL", 0)
Then, in the Step Expression field, specify the following expression:
That expression will obtain on each step the value of the(output.generating) ? { price = getAttrValue("PRICE").toNumber(); incVar("TOTAL", price); }
"PRICE"
attribute of the current iterated element and add it to the "TOTAL"
variable.
You can see that the basic expression that does the accumulation is enclosed in
the if construction. That if tests whether the output.generating
property is true
. That property indicates that the generator is currently
interpreting the iterator in order to generate its output. Only in that case we may add
the values to the total sum. Otherwise, without that testing, the "TOTAL"
variable may accumulate extra values and contain wrong result. See description of
GOMOutputInfo.status
property for more details about that.
After the interpreting of the Element Iterator is finished, the "TOTAL"
variable will contain the necessary sum, which can be printed further in the generated output.