About User Variables

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:

  1. Global Scope: Once created, the variable will exist during the entire generation session and can be accessed from any template.

  2. Template Scope: The variable is associated with the current processing of a template (during which it was created) and will exist until the processing is finished. The variable can be accessed within that template and any other subtemplates called from it.

    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.

  3. Stock-Section Scope: The variable is associated with a stock-section call (during which it was created) and will exist until the stock-section processing is finished. The variable can be accessed within that stock-section and any other stock-sections called from it.

    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:
(output.generating) ? { 
   price = getAttrValue("PRICE").toNumber();
   incVar("TOTAL", price);
}
That expression will obtain on each step the value of the "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.