...
Variables are a top-level resource within a document, containing a list of ?Document Object Model - Variable items:
| Code Block | ||
|---|---|---|
| xml | xml | <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>
|
...
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.
...
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. But regardless
| Note |
|---|
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
...
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.
| Code Block | lang | xml
|---|
<document>
<variables>
<item id="123-456-789" triggerChangeOnLoad="true" name="Variable1" displayName="First Variable" dataType="string" value="FIRST VALUE" />
</variables>
</document> |
...