Text variables
IDML text variables and page markers — the TextVariable definition, its VariableType kinds, TextVariableInstance in a story, and the <?ACE?> page-number codes.
A text variable is defined once in the design map and placed in stories as instances; page numbers and section names are markers instead.
In short A TextVariable in designmap.xml defines a piece of computed text: its
VariableType says what it computes (a running header, the last page number, the file
name, a date, a fixed string) and a typed …VariablePreference child holds its settings.
A story places it with a TextVariableInstance, which also stores the value InDesign last
composed as ResultText. The current, next and previous page number and the section
name are not variables but markers inside Content: <?ACE 18?> and <?ACE 19?>.
The definition: TextVariable
Each variable is a direct child of Document in the design map, after the preferences and
before the layers and spreads. Its settings are a typed child named after the kind of
variable:
VariableType | Settings child | Computes |
|---|---|---|
CustomTextType | CustomTextVariablePreference | TextBefore + the fixed Contents + TextAfter |
MatchParagraphStyleType | MatchParagraphStylePreference | text of the first or last paragraph in a style on the page (running header) |
MatchCharacterStyleType | MatchCharacterStylePreference | the same, over text in a character style |
LastPageNumberType | PageNumberVariablePreference | the label of the last page, of the document or of the section (Scope) |
ChapterNumberType | ChapterNumberVariablePreference | the document's chapter number |
FileNameType | FileNameVariablePreference | the document's file name, optionally with path and extension |
CreationDateType, ModificationDateType, OutputDateType | DateVariablePreference | a date in the variable's Format |
A custom variable keeps its value as a typed property:
<CustomTextVariablePreference TextBefore="" TextAfter=""><Properties><Contents type="string">Draft</Contents></Properties></CustomTextVariablePreference>.
| Attribute · TextVariable | Values | Paged | paged.set |
|---|---|---|---|
| Name | text | read · written | textVariableName |
| Self | reference / text | read · written | |
| VariableType | CustomTextType | FileNameType | PageCountType | CreationDateType | ModificationDateType | OutputDateType | ChapterNumberType | MatchParagraphStyleType | MatchCharacterStyleType | LastPageNumberType | XrefPageNumberType | XrefChapterNumberType | read · written | textVariableType |
The rules InDesign applies
These were measured by building each construct in InDesign 20.0.1 and reading its PDF:
- The last page number is a label, not a count. In a five-page document whose
numbering restarts at page 3,
LastPageNumberTypewith document scope prints "3". Use it for "page X of Y" only when numbering is continuous. - The chapter number belongs to the document, set in
ChapterNumberPreference(default 1), not to sections. - A running header carries forward. A page with no paragraph in the matched style shows
the value from the last page that had one.
DeleteEndPunctuationandChangeCaseapply afterwards. - Dates format the document's own clock for creation and modification, and the time of
output for
OutputDateType.
The instance: TextVariableInstance
Inside a story, a TextVariableInstance sits in a CharacterStyleRange where the value
appears. AssociatedTextVariable names the definition, and ResultText holds the value
InDesign last composed for that spot. A reader that does not compute variables can show
ResultText, knowing it reflects the layout at the time the file was saved.
| Attribute · TextVariableInstance | Values | Paged | paged.set |
|---|---|---|---|
| AssociatedTextVariable | reference | read · written | |
| ResultText | integer / text | read · written |
Page numbers and section markers
The current page number is not a variable. It is a processing instruction inside
Content:
In Content | Range attribute | Shows |
|---|---|---|
<?ACE 18?> | none | the current page number |
<?ACE 18?> | PageNumberType="NextPageNumber" | the number of the page the story continues on |
<?ACE 18?> | PageNumberType="PreviousPageNumber" | the number of the page the story came from |
<?ACE 19?> | none | the section marker of the page's section |
PageNumberType goes on the CharacterStyleRange that holds the marker. The number's
style (Arabic, Roman, letters) and the section marker's text come from the page's
Section; see sections and numbering.
In Paged: every variable kind in the table above is recomputed for the page it lands on; any other kind shows its
ResultText. Custom variables can be created and placed by scripts. Parsed, partly rendered
Frequently asked questions
Where is a text variable defined?
In designmap.xml, as a TextVariable child of Document, with a typed settings child
such as PageNumberVariablePreference.
What is ResultText?
The value InDesign last composed for one instance. It is correct for the layout at save
time and goes stale when text moves to other pages.
Is the page number a text variable?
No. The current, next and previous page numbers are <?ACE 18?> markers in the text;
only the last page number is a variable (LastPageNumberType).
What does <?ACE 19?> mean?
It is the section marker: the text the page's section defines as its marker.
Sections and numbering
The Section element — where numbering restarts, its PageNumberStyle, prefix and marker — and how pages, page-number markers and the chapter number use it.
Conditional text
How one IDML document carries several versions of its text — named conditions in the design map, runs that name them, and when their text is left out.