XML Structure
Variables are a top-level resource within a document, containing a list of ?Document Object Model - Variable items:
<document>
<variables>
<item id="123-456-789" name="Variable1" displayName="First Variable" dataType="string" value="FIRST VALUE" />
<item id="5845-59684-5" name="Variable2" displayName="Second Variable" dataType="image" imgXML="<item VALID_IMAGE_DEFINITION_XML />" />
</variables>
</document>
Updating Values and/or definitions using WebServices
Variables can be updated in a variety of ways, and you may not need to edit the full document's XML to accomplish this, if you want to make changes ONLY to variables: ?Updating Variable Values and Definitions.
Also keep in mind that the updated values may not immediately reflect in generated previews or PDF output for the document, if you don't use the "savedInEditor" property of the document: ?General XML Concepts
Variable Types
the "dataType" of a variable (default = "string"), can contain:
string
longtext
formattedtext
calculated
image
number
checkbox
date
list
table
color
paragraphstyle
characterstyle
font
coordinate
divider
buttonbar
See ?Variable Settings for more information on the various types.
Variable Values
Internally, all values are stored as strings inside the "value" property of the variable. The following types contain special formatting in that value:
formattedtext (see lower)
image: the "value" property is ignored, and the "imgXML" property is used, which should be empty (no image), or contain a valid definition XML (see ?Resource Item Definition XML, or ?Javascript Variable Input Forms, where the same is done from within JavaScript)
checkbox: "true" for a checked value, anything else = unchecked
list:
if variable's "multipleSelection" is not true, the variable's "value" contains the ID of the appropriate ?Document Object Model - VariableListItem object
if variable's "multipleSelection" is true, each list item's "isSelected" property is used, rather than the variable's "value" property
table: the variable's "value" is ignored, and the "tableRows" property (of type ?Document Object Model - VariableTableRows) is used
color / paragraphstyle / characterstyle / font: the ID of the selected item
coordinate: a valid unit (see ?General XML Concepts and ?Measurement Units for more information)
divider / buttonbar: value is not applicable
Next to the "value", there is also a "displayValue" which you may find in an edited document's XML. This is readonly, and is calculated by CHILI Editor itself, based on a variaty of rules depending on the variable's settings. For example (although you don't have to worry about those when generating/updating XML):
If the variable has a value, the "prefix" and "suffix" are prepended/appended
For lists allowing a single selection, the value or name is used, rather than the ID
For lists allowing multiple selection, the values of all selected items are concatenated (again using another prefix/suffix)
etc...
Formatted Text
A variable of type "formattedtext" is shown to the end user as a formatted text editor in the input form, with the matching features enabled.
Unsupported Behaviour
Regardless of that dataType, ANY variable (also "string" or "longtext" or "calculated", for example) which has a value which starts with "<TextFlow " and can be parsed as valid XML is inserted into a TextFrame's displayTextFlow as formatted text.
The "value" of the variable remains a string, but it contains a valid TextFlow XML, as described in TextFlow and ITextLayoutFormat XML
As you read, this behaviour might work, but is unsupported and might change in future versions. We strongly advise to use the FormattedText variable type to ensure futureproof compatibility.
Referencing Variables
In most cases, variables are simply referred to as a normal list item (by putting its ID in the relevant property/attribute). Within a text frame (if its "isVariable" property is "true"), the variable is referenced by inserting the %VARIABLE_NAME% pattern in the text frame's textFlow. See ?TextFrame XML for more information
Updating Variables with Actions
When updating variables that contain "onChange" actions, the action must be triggered on the variable by adding the attribute "triggerChangeOnLoad". This attribute should be added at the <item> node level, and should be added to each item that contains an action.
<document>
<variables>
<item id="123-456-789" triggerChangeOnLoad="true" name="Variable1" displayName="First Variable" dataType="string" value="FIRST VALUE" />
</variables>
</document>