w:fldSimple (Simple Field)

Description

w:fldSimple is the simple field element, combining the field instruction and its result in a single element (as opposed to the three-element begin/separate/end pattern). It is defined in ECMA-376 Part 1 §17.16.19.

The field instruction is stored in the w:instr attribute. Any run children of w:fldSimple contain the cached field result. Unlike complex fields (w:fldChar), the instruction and result are both in the same element.

Attributes

Examples

<!-- Simple date field -->
<w:fldSimple w:instr=" DATE \@ "MMMM d, yyyy" ">
  <w:r>
    <w:t>January 15, 2024</w:t>
  </w:r>
</w:fldSimple>

new SimpleField(
  new Run(new Text("January 15, 2024")))
{ Instruction = " DATE \\@ \"MMMM d, yyyy\" " };

<!-- Simple page number field (locked) -->
<w:fldSimple w:instr=" PAGE " w:fldLock="true">
  <w:r>
    <w:t>1</w:t>
  </w:r>
</w:fldSimple>

<!-- Simple document title field (marked dirty for update) -->
<w:fldSimple w:instr=" TITLE " w:dirty="true">
  <w:r>
    <w:t>My Document Title</w:t>
  </w:r>
</w:fldSimple>

// Locked page number
new SimpleField(
  new Run(new Text("1")))
{ Instruction = " PAGE ", Lock = true };

// Dirty (needs update) title
new SimpleField(
  new Run(new Text("My Document Title")))
{ Instruction = " TITLE ", Dirty = true };

<!-- Time field with multiple runs (bold + text) -->
<w:fldSimple w:instr=" TIME \@ "HH:mm:ss" ">
  <w:r>
    <w:rPr><w:b/></w:rPr>
    <w:t>14:30:45</w:t>
  </w:r>
</w:fldSimple>

<!-- Page count field -->
<w:fldSimple w:instr=" NUMPAGES ">
  <w:r>
    <w:t>10</w:t>
  </w:r>
</w:fldSimple>

// Time field with bold formatting
new SimpleField(
  new Run(
    new RunProperties(new Bold()),
    new Text("14:30:45")))
{ Instruction = " TIME \\@ \"HH:mm:ss\" " };

// Page count
new SimpleField(
  new Run(new Text("10")))
{ Instruction = " NUMPAGES " };

Field Types (Simple vs Complex)

Common Simple Field Instructions

Attributes and Behavior

Notes

• Simple vs Complex: Simple fields are read-only; use them for static metadata (PAGE, DATE, AUTHOR). Complex fields are updateable; use them for dynamic content (TOC, MERGEFIELD, REF).
• Caching: The result of a simple field is cached in the child w:r elements; the actual result depends on when the document was last generated.
• Dirty Flag: When w:dirty="true", the field result should be refreshed before display; Word typically updates dirty fields on open.
• Locking: When w:fldLock="true", the field instruction cannot be changed and the result won’t update; useful for fixed page numbers or static dates.
• Instruction Syntax: Field instructions follow Word’s field code syntax, not OOXML native syntax; they are domain-specific expressions using backslash-prefixed switches.
• Multiple Runs: Simple fields can contain multiple w:r elements; this allows mixed formatting in the result (e.g., bold DATE, colored TITLE).
• Empty Result: A simple field with no child runs or empty text is valid; typically means the field hasn’t been evaluated yet.
• Not Updatable: Unlike complex fields, simple fields cannot be updated by pressing F9 or Update Field in Word; they are display-only.
• Performance: Simple fields are lightweight; they don’t require regeneration logic or complex event handling.
• Accessibility: Ensure the field result is meaningful; empty or placeholder results may confuse screen readers.