<fldChar> (Complex Field Character)

This element specifies the presence of a complex field character at the current location in the parent run. A complex field character is a special character which delimits the start and end of a complex field or separates its field codes from its current field result.

A complex field is defined via the use of the two required complex field characters: a start character, which specifies the beginning of a complex field within the document content; and an end character, which specifies the end of a complex field. This syntax allows multiple fields to be embedded (or "nested") within each other in a document.

As well, because a complex field may specify both its field codes and its current result within the document, these two items are separated by the optional separator character, which defines the end of the field codes and the beginning of the field contents. The omission of this character shall be used to specify that the contents of the field are entirely field codes (i.e. the field has no result).

example: 
<w:fldChar w:type="start" />
<w:r>
  <w:instrText>AUTHOR</w:instrText>
</w:r>
<w:fldChar w:type="separate" />
<w:r>
  <w:t>Rex Jaeschke</w:t>
</w:r>
<w:fldChar w:type="end" />

The three <fldChar> elements specify:

  • The beginning of the field, using the @type attribute value of start

  • The separator between the field codes and the current field results, using the @type attribute value of separate

  • The end of the field, using the @type attribute value of end

If a complex field character is located in an inappropriate location in a WordprocessingML document, then its presence shall be ignored and no field shall be present in the resulting document when displayed. Also, if a complex field is not closed before the end of a document story, then no field shall be generated and each individual run shall be processed as if the field characters did not exist (i.e. the contents of all field code run content shall not be displayed, and the field results shall be displayed as literal text).

example: 
<w:body>
  <w:p>
    <w:fldChar w:type="start" />
    <w:r>
      <w:instrText>AUTHOR</w:instrText>
    </w:r>
    <w:fldChar w:type="separate" />
    <w:r>
      <w:t>Rex Jaeschke</w:t>
    </w:r>
  </w:p>
</w:body>

The complex field is technically incorrect since no end character exists in the main document story. The resulting content shall be interpreted as though no field characters exist, resulting in only the literal text Rex Jaeschke being displayed in the document. ]

Parent Elements

<r> (§7.1.2.87); <r> (§2.3.2.23)

Child Elements

Subclause

<ffData> (Form Field Properties)

§2.16.17

<fldData> (Custom Field Data)

§2.16.19

<numberingChange> (Previous Numbering Field Properties)

§2.13.5.29

Attributes

Description

<dirty> (Field Result Invalidated)

Specifies that this field has been flagged by an application to indicate that its current results are invalid (stale) due to other modifications made to the document, and these contents should be updated before they are displayed if this functionality is supported by the next processing application.

[: This functionality allows applications with limited subsets of the full functionality of this Office Open XML Standard to process Word Open XML documents without needing to understand and update all fields based on the semantics for their field codes.

For example, an application can add a new paragraph and flag the table of contents as dirty, without needing to understand anything about how to recalculate that field's content. ]

If this attribute is omitted, then its value shall be assumed to be false. If the @type of the current field character is not start, then his setting may be ignored.

<w:fldChar w:type="start" w:dirty="true"/>
<w:r>
  <w:instrText>TOC /l 1-3</w:instrText>
</w:r>
<w:fldChar w:type="separate"/>
…

The @dirty attribute value of true specifies that the contents of this field are no longer current based on the contents of the document, and should be recalculated whenever an application with this functionality reads the document. ]

The possible values for this attribute are defined by the ST_OnOff simple type (§2.18.67).

<fldCharType> (Field Character Type)

Specifies the type of the current complex field character in the document.

…
<w:fldChar w:type="separate" />
…

The @type attribute value of separate specifies that this is a complex field separator character; therefore it is being used to separate the field codes from the field contents in a complex field. ]

The possible values for this attribute are defined by the ST_FldCharType simple type (§2.18.33).

<fldLock> (Field Should Not Be Recalculated)

Specifies that the parent complex field shall not have its field result recalculated, even if an application attempts to recalculate the results of all fields in the document or a recalculation is explicitly requested.

If this attribute is omitted, then its value shall be assumed to be false. If the @type of the current field character is not start, then his setting may be ignored.

<w:fldChar w:type="start" w:fldLock="true"/>
  …
<w:fldChar w:type="separate"/>
<w:r>
  <w:t>field result</w:t>
</w:r>
<w:fldChar w:type="end" />

The @fldLock attribute value of true specifies that the contents of this field shall remain field result regardless of the actual result of the current field codes. ]

The possible values for this attribute are defined by the ST_OnOff simple type (§2.18.67).

The following XML Schema fragment defines the contents of this element:

<complexType name="CT_FldChar">
	<choice>
	<element name="fldData" type="CT_Text" minOccurs="0" maxOccurs="1"/>
	<element name="ffData" type="CT_FFData" minOccurs="0" maxOccurs="1"/>
	<element name="numberingChange" type="CT_TrackChangeNumbering" minOccurs="0"/>
	</choice>
	<attribute name="fldCharType" type="ST_FldCharType" use="required"/>
	<attribute name="fldLock" type="ST_OnOff"/>
	<attribute name="dirty" type="ST_OnOff"/>
</complexType>