2. How it works

To include form fields in an OOXML document one must embed custom elements in the XSL-FO tree. These elements must be in a separate namespace specified by XMLmind. This namespace - referred to by prefix sdt in this document - must be declared in the opening tag of the root element of the XSL-FO tree, as shown below.

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
         xmlns:sdt="http://www.xmlmind.com/foconverter/xsl/extensions/docx/sdt">

2.1. Text field example

Consider the XSL-FO snippet below:

<fo:block margin-left="1cm" margin-right="1cm">Name: <fo:inline
border="solid 1pt blue" padding="1mm"><sdt:text-field binding="name"
prompt="[Enter your name here.]" title="Name" /></fo:inline></fo:block>

The sdt:text-field element will be converted by XFC to a plain text SDT, which provides the functionality of a basic text field. The prompt attribute specifies placeholder text to be initially displayed in the field. The sdt:text-field element is wrapped in an fo:inline object that carries presentation properties. The initial display of the whole block in MS-Word 2007 is shown below. The next image shows the appearance of the field when selected, and the last one shows the field once filled.

Figure 7.1. Text field (initial display)

Text field (initial display)

Figure 7.2. Text field (selected)

Text field (selected)

Figure 7.3. Text field (filled)

Text field (filled)

The binding attribute of the sdt:text-field element establishes the mapping between the field and an XML element in the Custom XML Data part. In the simplest case the value of this attribute is an XML element name. The Custom XML Data part will be automatically generated by XFC, in the form of a simple XML instance where all elements associated with form fields are children of the root element. Assuming the document contains no other field, XFC will therefore generate the XML instance below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <name></name>
</root>

When saving the document after an editing session MS-Word will store the current value of the field as the content of the name element in the Custom XML Data part, as shown below.

<?xml version="1.0" encoding="UTF-8"?><root>
  <name>John Smith</name>
</root>

2.2. Drop-down list example

Consider the XSL-FO snippet below:

<fo:block margin-left="1cm" margin-right="1cm">Favorite Animal:
<fo:inline border="solid 1pt blue" padding="1mm"><sdt:drop-down-list
    binding="favorite-animal" initial-value="cat"
    title="Favorite Animal">
    <sdt:list-entry value="cat" />

    <sdt:list-entry value="dog" />

    <sdt:list-entry value="hamster" />
  </sdt:drop-down-list></fo:inline></fo:block>

The sdt:drop-down-list element will be converted by XFC to a drop-down list SDT, which provides the ability to select a single value from a predefined list. The list entries are specified by the sdt:list-entry children. The initial-value attribute of the sdt:drop-down-list element specifies the initial value of the field. The initial display of the whole block in MS-Word 2007 is shown below. The next image shows the appearance of the field while selecting an entry in the list.

Figure 7.4. Drop-down list (initial display)

Drop-down list (initial display)

Figure 7.5. Drop-down list (selecting an entry)

Drop-down list (selecting an entry)

The initial-value attribute differs from the prompt attribute in that the specified value is initially stored in the Custom XML Data part. Assuming the document contains no other field, XFC will therefore generate the Custom XML Data part below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <favorite-animal>cat</favorite-animal>
</root>

2.3. Specifying a Custom XML Data template

Sometimes it may be desirable to have form data stored in an XML instance more complex than the default instance generated by XFC. In this case a Custom XML Data template may be specified by inserting an sdt:configuration element before the first fo:page-sequence object in the XSL-FO tree, e.g.:

<sdt:configuration custom-xml-template="custom.xml" />

The custom-xml-template attribute specifies the URL of an XML template to be used as the initial content of the Custom XML Data part. This XML template must be encoded in UTF-8 or UTF-16.

When a Custom XML Data template is specified, the binding attribute of a form field associated with an XML element in the Custom XML Data part references that particular element by means of an XPath 1.0 expression. For instance, consider the XML template below:

<?xml version="1.0" encoding="UTF-8"?>
<order>
  <product>
    <reference />
    <quantity />
  </product>
  <product>
    <reference />
    <quantity />
  </product>
</order>

To associate the reference child of the first product element with a form field one would set the binding attribute value of that field to /order/product[1]/reference. Moreover, when a Custom XML Data template is specified the initial-value attribute of form fields is ignored. If a field is to be initialized the initial value must be stored in the Custom XML Data template as the content of the XML element associated with that field.

2.4. Extracting the Custom XML Data part

Office Open XML documents are basically ZIP archives, so the Custom XML Data part can be easily extracted. In accordance with MS-Word's naming scheme XFC stores the Custom XML Data part in ZIP entry customXml/item1.xml.