### 12.1 Understanding how DITA2Go user variables work

DITA2Go provides the following ways to capture element content in variables that you can subsequently use in macros:

- Assign property Var to an element; see §11.2 Specifying properties of element types. The variable has the same name as the element.
- Assign the name of a variable to an element path; see §12.2 Assigning variable names to element paths.

Either way, what you get is a DITA2Go user variable. If an element is neither listed with a path in [VariableMaps] nor assigned property Var in [ElementTypes], no user variable is created for it.

If you specify that an element is to function as a DITA2Go user variable, either by listing an element path in [VariableMaps] or by setting Var for the element in [ElementTypes] (explicitly or by default), DITA2Go stores the first instance as a regular user variable. If the same element or path occurs again in your document, the variable begins a list, and every subsequent instance is added to that list. A multiple-instance user variable behaves like a read-only list variable; see §37.4 Using multiple-value list variables.

Accessing single-instance user variables

You can access the content of a single-instance user variable in a macro as <$$varname>, provided you have not already defined a DITA2Go macro variable of the same name, either in [MacroVariables] (see §37.3 Using macro variables) or by assigning a value to that name in a macro. Elements assigned property Var by default (listed in Table 11-1) appear just once in each DITA document, in a bookmap. For these metadata items, only one value is captured, and you do not need to use an index number to access the value. For example, to use the content of mainbooktitle in a macro, you would reference <$$mainbooktitle>; see §37.3 Using macro variables.

Accessing multiple-instance user variables

You can access any instance of a multiple-instance user variable (after the first instance) as <$$varname[index]>, where index is a number from 1 to N. You can access the value of N with <$$varname[]>. Each value is referenced by specifying the name and the index-number-minus-1 of its occurrence. For example, if you (perhaps foolishly) assign property Var to element title, the content of the third instance of title in your document will be available as <$$title[2]> (because the first instance is <$$title> and the second is <$$title[1]>). The 568th instance will be <$$title[567]>. If you reference just <$$title>, you get the first instance.

User variables are read-only

You cannot alter the content of a user variable derived from a DITA element; these variables are read-only. However, you can override the content of a user variable by assigning a value to a macro variable of the same name; thereafter, the user variable is no longer accessible.

Previous Topic: 12. Creating and deploying user variables

Next Topic: 12.2 Assigning variable names to element paths

Parent Topic: 12. Creating and deploying user variables

Sibling Topics:

12.2 Assigning variable names to element paths

12.3 Including user variables in DITA2Go macros

12.4 Deploying user variables in template macros