Text variables

A text variable is a named, computed string — like a file name or chapter number — that IDML splits into a TextVariable definition under Document and a TextVariableInstance carrying the baked value where it appears.

In short: A text variable is a named, computed string — a file name, a chapter number, a running header, a date — that InDesign places into the flowing text and re-derives whenever the document changes. IDML records it at two altitudes: a TextVariable definition that lives once under Document in the design map, and one or more TextVariableInstance instances that sit in the stories where the value actually appears. Each instance carries its evaluated value frozen in a ResultText attribute — a snapshot from the last export. This page is the document-level reference for the definition, the VariableType kinds it can take, and the shape of the value an instance carries; our parser records the definition and inlines the instance's ResultText verbatim without ever recomputing it.

A text variable is a named, computed string — a file name, a chapter number, a running header, a date — that InDesign places into the flowing text and re-derives whenever the document changes. IDML splits it into two parts at two altitudes: a definition that lives once under Document in the design map, and one or more instances that sit in the stories where the value actually appears.

This page is the document-level reference: the TextVariable definition and the shape of the value an instance carries. The run-level mechanics — how an instance becomes characters inside a CharacterStyleRange, and how page-number markers differ — are documented once in stories & text → text variables. This page links there rather than repeating it.

The definition: TextVariable

Each text variable is declared by a TextVariable element directly under Document in designmap.xml. The parser records three things from it — the id, the display name, and the kind — at paged-parse/src/designmap.rs:227.

VariableType kinds

VariableType names the rule InDesign would run to produce the value. The enumeration covers the variable families InDesign offers:

We record VariableType so a consumer can tell what a variable is, but the renderer never acts on it: it does not run the rule. A ChapterNumberType variable is parsed, but its number is not re-derived from the book — the parsed value is the frozen ResultText on the instance, not a recomputed chapter count.

Parsed, not yet renderedVariableType is recorded but never executed; chapter-number and running-header rules are parsed-not-acted — paged-parse/src/designmap.rs:227

The instance: TextVariableInstance and ResultText

Where the variable's value appears in the text, the story carries a TextVariableInstance element inside a CharacterStyleRange's Content. It holds the value verbatim in ResultText and points back at its definition through AssociatedTextVariable. When the parser reaches one, it appends ResultText to the current run — paged-parse/src/story.rs:1643 — so by the time you hold a run string, the variable is just more characters.

ResultText is a snapshot — whatever InDesign computed the last time it composed the document. A "Running Header" instance carries the header text as of export; a "File Name" instance carries the file name as of export. The renderer inlines that snapshot; it does not re-derive the value from the current layout. So a running header will not update if you move the paragraph it tracks, and a chapter number will not change if the document's place in a book changes.

Parsed, not yet renderedResultText is the frozen value from the last export; it is not recomputed at render time — paged-parse/src/story.rs:1643

What this means in practice

• Re-display is faithful, recomputation is not. Because the value is baked, a consumer reproduces exactly what InDesign last showed — but it will not catch up to edits made outside InDesign.
• The page-number variable is a separate path. The current- and next-page numbers are not stored as TextVariableInstance; they are processing instructions (<?ACE 18?> / <?ACE 19?>) that resolve to the live page label at render time. That mechanism — and the private-use marker codepoints it uses — is detailed in stories & text → text variables, and the labels it resolves to are explained in sections and numbering.
• For extraction, a TextVariableInstance contributes its ResultText like any other characters; see extract all text.

Frequently asked questions

What is a text variable in IDML? A text variable is a named, computed string — such as a file name, chapter number, running header, or date — that InDesign places into the flowing text. IDML stores it as a TextVariable definition under Document plus a TextVariableInstance in each story where the value appears.

What does the ResultText attribute hold? ResultText holds the variable's value as a literal string, computed as of the last export and inlined into the run text exactly as written. It is a frozen snapshot, so our renderer reproduces what InDesign last showed but never re-derives the value from the current layout.

Does the renderer recompute a chapter number or running header? No. The VariableType is recorded so a consumer can tell what kind of variable it is, but the rule it names is never executed — the parsed value is always the frozen ResultText, not a recomputed chapter count or a re-tracked header.

Is the current page number stored as a text variable? No. The current- and next-page numbers are not TextVariableInstance elements; they are processing instructions (<?ACE 18?> / <?ACE 19?>) that resolve to the live page label at render time. That separate path is detailed in stories & text → text variables.