WordprocessingML

1. Components of WordprocessingML
• Main Document
• Paragraphs & Rich Formatting
– Runs
– Run Content
• Tables
• Custom Markup
• Sections
• Styles
– Paragraph
– Character
– Numbering
– Table
– Document Defaults
• Fonts
• Numbering
• Headers/Footers
• Footnotes/Endnotes
• Glossary Document
• Annotations
– Comments
– Revisions
– Bookmarks
• Mail Merge
• Document Settings
– Web Settings
– Compatibility Settings
• Fields & Hyperlinks
• Odds & Ends (Textboxes, Subdocuments, Extensibility)
Ecma/TC45/2006/038 (Rev.)

2. WordprocessingML – Fields &
Hyperlinks

3. Fields
• Represent non-static text in a word processing
document
– Most text is static; only changes based on user
interaction
– This is not suitable for some content (e.g. page
numbers)
– Fields specify text which should be calculated
based on a specific formula

4. Fields Example
• Consider a field which should always render
today's date
• Entering the date as static text wouldn't be
sufficient, as today's date is dynamic
• Therefore, a field must be inserted which
specifies that it should always display the
current date.

5. Field Components
• Fields are comprised of two primary
components:
– Field codes
• the instructions that describe to the consumer how to
calculate the field
– Field results
• the results of the last calculation of the field codes
(when appropriate)
• For example, WordprocessingML does not store the
results of the page number field, because it doesn't
store the concept of pages

6. Field Components Example
• Consider the AUTHOR field, which shows the
document's author property:
• Field results show:
• Field codes show:

7. Fields in WordprocessingML
• These two components can be represented in
two distinct ways in WordprocessingML:
– Simple fields
– Complex fields
• Either syntax can be used, depending on the
requirements in context

8. Simple Fields
• Specified by the fldSimple element
• Used when the field instructions hold no
formatting

9. Simple Fields
Field codes
Field results
Note that Word places a run property on the field results that prevents it from being
spell or grammar checked

10. Complex Fields
• Specified by three delimiter elements
– Field start
– Field separator
– Field end
• Used when there is formatting on the fields
codes themselves
– Therefore, they need to be persisted as
WordprocessingML

11. Complex Fields Example
• Let's create an IF field and format the field
codes:
• Now, we need to persist that formatting
– Therefore, this can't be a simple field

12. Complex Fields Example
• Field start character

13. Complex Fields Example
• Field codes
• Note that field codes do not use the <t>
element
– So that you can easily exclude field code text

14. Complex Fields Example
• Field separator character
– This delimits the end of the field codes, and start
of the field results

15. Complex Fields Example
• Field results

16. Complex Fields Example
• Field end character

17. Complex Fields
• Other reasons why fields must be complex:
– Revision marking
– Fields can span multiple paragraphs (i.e. they're
not well-formed)

18. Locked Fields
• A field can be locked, in which case, its result
cannot be updated
• Set via a fldLock attribute on the field's
fldSimple or field start elements

19. Updating Fields
• Some fields should be automatically updated
with each edit (e.g. the PAGENUM field), while
others should not update unless explicitly
asked to do so (e.g. the AUTHOR field)
• Therefore, fields are of three types:
– Hot (always update)
– Warm (update on open save, or print)
– Cold (never automatically update)

20. Caching Field Results
• Producers may wish to save a document with
fields and deliberately mark some cold fields
as 'stale':
– For example, when the producer knowingly
invalidated the field's result, but was not
sophisticated enough to recalculate the field

21. Caching Field Results
• A 'dirty' bit on any field specifies that a
producer should treat the results of that field
as stale, and potentially offer UI to update the
field
– This is done via the dirty attribute
• This can also be done on the document level
using the document's settings

22. Field Types
• Fields can be divided into eight categories:
– Date and Time
– Document Automation
– Document Properties
– Equations and Formulas
– Links and References
– Mail Merge
– Numbering
– User Information

23. Date and Time
• Field types:
– CREATEDATE (creation date)
– DATE (current date)
– EDITTIME (time edited)
– PRINTDATE (last printed date)
– SAVEDATE (last saved date)
– TIME (current time)

24. Document Automation
• Field types:
– COMPARE (logical comparison)
– DOCVARIABLE (display document variable)
– GOTOBUTTON (link button)
– IF (logical IF statement)
– MACROBUTTON (run application-specific code)
– PRINT (print the document)

25. Document Properties
• Field types:
– AUTHOR (document author property)
– COMMENTS (document comments property)
– DOCPROPERTY (show OLE document property)
– FILENAME (file name)
– FILE SIZE (file size)
– INFO (document information)

26. Document Properties
• Field types (cont'd):
– KEYWORDS (document keywords property)
– LASTSAVEDBY (last saved by property)
– NUMCHARS (number of characters)
– NUMPAGES (number of pages)
– NUMWORDS (number of words)
– SUBJECT (subject document property)
– TEMPLATE (document template file name)
– TITLE (title document property)

27. Equations and Formulas
• Field types
– =.. (formulas)
– ADVANCE
– EQ (equation)
– SYMBOL (show symbol)

28. Index and Tables
• Field types:
– INDEX (document index)
– RD (referenced document)
– TA (table of authorities entry)
– TC (table of contents entry)
– TOA (table of authorities)
– TOC (table of contents)
– XE (cross reference)

29. Links and References
• Field types:
– AUTOTEXT (show AutoText entry)
– AUTOTEXTLIST (user choice of AutoText entry)
– HYPERLINK
– INCLUDEPICTURE (import external image)
– INCLUDETEXT (import external text)
– LINK (link to text)

30. Links and References
• Field types (cont'd):
– NOTEREF (footnote/endnote reference)
– PAGEREF (page reference)
– QUOTE (show text)
– REF (reference to bookmark or paragraph)
– STYLEREF (reference to styled text)

31. Mail Merge
• Field types (covered later):
– ADDRESSBLOCK
– ASK
– BARCODE
– COMPARE
– DATABASE
– FILLIN
– GREETINGLINE
– IF

32. Mail Merge
• Field types (covered later):
– MERGEFIELD
– MERGEREC
– MERGESEQ
– NEXT
– NEXTIF
– SET
– SKIPIF

33. Numbering
• Field types:
– AUTONUM (legacy numbering)
– AUTONUMLGL (legacy legal numbering)
– AUTONUMOUT (legacy outline numbering
– LISTNUM (legacy list numbering)
– PAGE (number of pages)
– REVNUM (revision number property)
– SECTION (section number)

34. Numbering
• Field types (cont'd):
– SECTIONPAGES (pages in section)
– SEQ (sequence)

35. User Information
• Field types:
– USERADDRESS (user address)
– USERINITIALS (user intials)
– USERNAME (user name)

36. Field Formulas
• A field code can involve a operation via a
formula, which consists of:
– Constants
– Bookmark references
– Numbers
– Logical operators
– Functions

37. Field Formulas
• Constants
– Formulas can use any constant value (e.g. an
integer)
• Bookmarks
– Can supply a constant for another field (e.g. Result
* 10 will look for the value of a bookmark called
'Result')
• Numbers

38. Operators
Operators
Operator Description Precedence
- Unary minus highest
^ Powers and roots
* Multiplication
/ Division
% Percentage
+ Addition
- Subtraction
= Equal to
<> Not equal to
< Less than lowest
<= Less than or equal to
> Greater than
>= Greater than or equal to

39. Functions
Functions
Function Description
ABS(x) Returns the absolute value of x.
AND(x,y) Returns 1 if the logical expressions x and y are both true;
otherwise, it returns 0.
AVERAGE(list) Returns the average value of the items in list.
COUNT(list) Returns the number of items in list.
DEFINED(x) Returns 1 if the expression x is well formed; otherwise, it
returns 0.
FALSE Returns 0.
INT(x) Returns the value of the integer part of x.
(list) Returns the largest value in list.
MIN(list) Returns the smallest value in list.

40. Functions (cont'd)
MOD(x,y) Returns the value x - ny, for some integer n such that, if y is
nonzero, the result has the same sign as x and magnitude less than
the magnitude of y. If y is zero, a diagnostic SHALL be
issued. (y need not be a whole number.)
NOT(x) Returns 0 if the logical expression x is true, or 1 if the expression is
false.
OR(x,y) Returns 1 if either or both logical expressions x and y are true;
otherwise, it returns 0.
PRODUCT(list) Returns the result of multiplying together all members in list.
ROUND(x,y) Returns the value of x rounded to the specified number of decimal
places indicated by floor(y), where floor has the mathematical
meaning. If y is negative, any fractional part is discarded and the
integer part of the value is rounded to the corresponding power
of 10.
SIGN(x) Returns 1 if x is positive; returns 0 if x is zero; and returns –1 if x is
negative.
SUM(list) Returns the sum of the items in list.
TRUE Returns 1.

41. Common Field Formatting
• Field results can be of three formats:
– Dates
– Numbers
– Text
• Each result type can be formatted within the
field codes

42. Date Field Formatting
DATE @ "M/d/yyyy"
DATE @ "dddd, MMMM dd, yyyy" Tuesday,
DATE @ "MMMM d, yyyy"
DATE @ "M/d/yy"
DATE @ "yyyy-MM-dd" 2006-01-03
DATE @ "d-MMM-yy" 3-Jan-06
DATE @ "M.d.yyyy" 1.3.2006
DATE @ "MMM. d, yy"
DATE @ "d MMMM yyyy" 3 January 2006
DATE @ "MMMM yy" January 06
DATE @ "MMM-yy" Jan-06
DATE @ "M/d/yyyy h:mm am/pm"
DATE @ "M/d/yyyy h:mm:ss am/pm" 5:28:34 PM
DATE @ "h:mm am/pm"
DATE @ "h:mm:ss am/pm" 5:28:34 PM
DATE @ "HH:mm" 17:28
DATE @ "HH:mm:ss" 17:28:34

43. Number Field Formatting
Numeric Formatting Picture Items
Picture Item Description
0 Specifies the requisite numeric positions to display in the result. If the result
does not include a digit in that position, 0 is displayed. [Example: In a US-
English context, =4+5 # 00.00 displays "09.00". end example]
# Specifies the requisite numeric positions to display in the result. If the result
does not include a digit in that position, a space is displayed. Extra fractional
digits are rounded off. [Example: =9+6 # $### displays "$ 15". end
example]
x Drops digits to the left of the x placeholder. If the placeholder is to the right
of the decimal point, the result is rounded to that place. [Example: In a US-
English context, =111053+111439 # x## displays "492",
=1/8 # 0.00x displays "0.125", and =3/4 # .x displays ".8". end
example]
. Indicates the radix-point position. [Example: In a US-English context,
=95.4 # $###.00 displays "$ 95.40. end example] The radix-point
character used is locale-specific.
, Separates groups of three digits. [Example: In a US-English context,
=2456800 # $#,###,### displays "2,456,800". end example] The
separator character used is locale-specific.
- Prepends a minus sign to a negative result, or prepends a space if the result is
positive or 0. [Example: =80-90 # -## displays "-10", while =90-
80 # -## displays " 80". end example]

44. Number Field Formatting (cont'd)
+ Prepends a plus sign to a positive result, a minus sign to a negative result, or a
space if the result is 0. [Example: =90-80 # +## displays "+10", and =80-
90 # +## displays "-10". end example]
Other character Includes the specified character in the result at that position. [Example:
=33 # ##% displays "33%". end example]
'text' Includes text in the result. [Example: In a US-English context, if is a
bookmark for 26.5, =*15% # "##0.00 'is the sales tax'" displays
"$ 3.98 is the sales tax". end example]
`numbered-item` Includes, in Arabic numerals, the number of the preceding item numbered as a
caption or resulting from a SEQ field (§8.58). numbered-item shall be the same
name as identifier in that SEQ field. [Example: =SUM(A1:D4) # "##0.00
'is the total of Table' `table`" displays "456.34 is the total
of Table 2". end example]
positive-result ;
negative-result
Specifies different sets of picture items for positive and negative results. A
zero value uses the positive picture. [Example: =Sales95 # $#,##0.00;-
$#,##0.00 displays that bookmark's positive values using $#,##0.00, and it's
negative values using -$#,##0.00. end example]
positive-result ;
negative-result ;
zero-result
Specifies different sets of picture items for positive, negative, and zero results.
[Example: =Sales95 # $#,##0.00;-$#,##0.00;$0 displays that
bookmark's positive values using $#,##0.00, it's negative values using -
$#,##0.00, and its zero values using $0. end example]

45. Text Field Formatting
General Formatting Switch Arguments
Switch Argument Description
ALPHABETIC Formats a numeric result as one or more uppercase alphabetic Latin characters. Value 1 results in
the letter A, value 2 results in the letter B, and so on up to value 26, which results in the letter Z.
26 is subtracted from the value and if the result is non-zero, the whole process is repeated until
the value is zero. [Example: =54 * ALPHABETIC results in "BBB". end example]
alphabetic Formats a numeric result as one or more lowercase alphabetic Latin characters. Value 1 results in
the letter a, value 2 results in the letter b, and so on up to value 26, which results in the letter z.
26 is subtracted from the value and if the result is non-zero, the whole process is repeated until
the value is zero. [Example: =54 * alphabetic results in "bbb". end example]
Arabic Formats a result using Arabic cardinal numerals. [Example: For page 123, PAGE * Arabic
results in "123". end example]
ArabicDash Formats a result using Arabic cardinal numerals, with a prefix of "- " and a suffix of " -".
[Example: For page 123, PAGE * ArabicDash results in "- 123 -". end example]
Caps Capitalizes the first letter of each word. [Example: USERNAME " smith" * Caps results in
"", whereas USERNAME "marysmith" * Caps results in "Marysmith". end example]
CardText Formats a result as cardinal text. By default, the result is in lowercase; however, a capitalization
switch can be used to change that. [Example: For page 123, PAGE * CardText results in
"one hundred twenty-three", while PAGE * CardText * Caps results in "One
Hundred Twenty-Three". end example]

46. Text Field Formatting (cont'd)
DollarText Formats a result in the following form:
integer-part-as-cardinal-text and nn/100
The fractional part is rounded to two decimal places, nn, and is formatted using Arabic
cardinal numerals. [Example: =1234.567 * DollarText results in "one thousand
two hundred thirty-four and 57/100". end example]
FirstCap Capitalizes the first letter of the first word. [Example: USERNAME " smith" *
FirstCap results in " smith". end example]
Hex Formats the result using hexadecimal digits. By default, the result is in uppercase; however,
a capitalization switch can be used to change that. [Example: For page 355,
PAGE * Hex * Lower results in "ff". end example]
Lower All letters are lowercase. [Example: USERNAME " smith" * Lower results in
" smith". end example]
OrdText Formats a result as ordinal text. By default, the result is formatted in lowercase; however, a
capitalization switch can be used to change that. Apart from being used to round off the
whole number part, the fractional part is not used. [Example: =1234.567 * OrdText
results in "one thousand two hundred thirty-fifth". end example]

47. Text Field Formatting (cont'd)
Ordinal Formats a result using ordinal Arabic numerals. By default,
the suffixes are formatted in lowercase; however, a
capitalization switch can be used to change that. [Example:
=32 * Ordinal results in "32nd", while
=33 * Ordinal * Upper results in "33RD". end
example]
Formats a result using uppercase numerals. [Example: For
page 123, PAGE * results in "CXXIII". end example]
roman Formats a result using lowercase numerals. [Example: For
page 123, PAGE * roman results in "cxxiii". end
example]
Upper All letters are uppercase. [Example: USERNAME " smith"
* Upper results in "MARY SMITH". end example]

48. Hyperlinks
• Hyperlinks are simply another type of field
– As we saw in the field types list, they are
represented using the HYPERLINK field
• However, WordprocessingML provides a
specific syntax for writing out hyperlinks
– This is defined using the hyperlink element

49. Hyperlinks
• Whenever the hyperlink can be saved as a
simple field, it uses the hyperlink element
– This element specifies the hyperlink target as an
explicit relationship on the hyperlink

50. Hyperlinks
• Whenever the hyperlink requires complex
field syntax (e.g. the field codes are
formatted), it's just another complex field
with the HYPERLINK field code and no
relationship

51. Disclaimer
This presentation is for informational purposes only, and should
not be relied upon as a substitute or replacement for Microsoft
formal file format documentation, which is available at the
following website: https://msdn.microsoft.com/en-
us/library/cc313118(v=office.12).aspx. Any views or opinions
presented in this material are solely those of the author and do
not necessarily represent those of Microsoft. Microsoft
disclaims all liability for mistakes or inaccuracies in this
presentation.