3. Reference Material

This section provides a comprehensive description of the custom elements that make up the XSL-FO extension for Office Open XML. 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">

There are five elements that translate into a form field:

These are inline-level elements that may appear anywhere inline-level Formatting Objects are allowed.

3.1. Generic attributes

The attributes described below apply to all form fields, except for the initial-value and prompt attributes that do not apply to the sdt:picture element.

  • binding

    This attribute establishes the mapping between a 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. When a Custom XML Data template is specified the attribute value is an XPath 1.0 expression that identifies the XML element associated with the field. If this attribute is omitted no mapping is established.

  • editable

    This attribute specifies whether or not the field content is editable. Possible values are true (default) and false.

  • initial-value

    This attribute specifies the initial value of the field. The specified value will be stored in the Custom XML Data part, unless a Custom XML Data template is in use. (This attribute has no effect if a Custom XML Data template has been specified. In this case the initial value must be stored in the Custom XML Data template as the content of the XML element associated with the field.)

  • locked

    This attribute specifies whether or not the field is locked. Possible values are true (default) and false. (The feature of a locked field is that it cannot be deleted from the document.)

  • prompt

    This attribute specifies placeholder text to be initially displayed in the field if no initial value is provided. (If both the prompt and initial-value attributes are specified the latter will take precedence.)

  • title

    This attribute specifies the field title. This title is displayed as part of the field outline when the field is selected. The default value is specific to each field type.

3.2. sdt:text-field

This element is converted to a plain text SDT, which provides the functionality of a basic text field.

Figure 7.6. Text field

Text field

Attributes:

  • binding

    See generic attributes.

  • editable

    See generic attributes.

  • initial-value

    See generic attributes.

  • locked

    See generic attributes.

  • multi-line

    This attribute specifies whether or not line breaks are allowed in the field value. Possible values are true and false (default).

  • prompt

    See generic attributes.

  • title

    See generic attributes. (The default value is Text Field).

Content model:

EMPTY

3.3. sdt:drop-down-list

This element is converted to a drop-down list SDT, which provides the ability to select a single value from a predefined list.

Figure 7.7. Drop-down list

Drop-down list

Attributes:

  • binding

    See generic attributes.

  • editable

    See generic attributes.

  • initial-value

    See generic attributes.

  • locked

    See generic attributes.

  • prompt

    See generic attributes.

  • title

    See generic attributes. (The default value is Drop-Down List).

Content model:

(sdt:list-entry)+

3.4. sdt:list-entry

This element specifies an entry in the list of possible values of a drop-down list or combo box SDT.

Attributes:

  • display-text

    This attribute specifies alternative text to be displayed when this entry is selected. (By default the actual entry value is displayed.)

  • value

    This attribute specifies the actual entry value. This is the value that will be stored in the Custom XML Data part when this entry is selected. This attribute is required. (The sdt:list-entry element is ignored if this attribute is omitted.)

Content model:

EMPTY

3.5. sdt:combo-box

This element is converted to a combo box SDT, which combines a text field and a drop-down list.

Attributes:

  • binding

    See generic attributes.

  • editable

    See generic attributes.

  • initial-value

    See generic attributes.

  • locked

    See generic attributes.

  • prompt

    See generic attributes.

  • title

    See generic attributes. (The default value is Combo Box).

Content model:

(sdt:list-entry)+

3.6. sdt:date

This element is converted to a date SDT, which is a text field with date semantics. This SDT provides a date picker for fast and secure input, though a date value may be typed in as well.

Figure 7.8. Date

Date

Attributes:

  • binding

    See generic attributes.

  • editable

    See generic attributes.

  • format

    This attribute specifies the date format. (This format is used by the date picker but is not enforced when a value is typed in directly.) The attribute value is a character string in which the following variables are recognized:

    VariableExpanded Value
    %Dday of month (01-31)
    %Mmonth (01-12)
    %Yyear (4 digits)
    %yyear (last 2 digits)

    The default value is %Y-%M-%D.

  • initial-value

    See generic attributes.

  • locked

    See generic attributes.

  • prompt

    See generic attributes.

  • title

    See generic attributes. (The default value is Date).

Content model:

EMPTY

3.7. sdt:picture

This element is converted to a picture SDT, which provides the ability to select, display and edit images. The value of this field - stored as the content of the associated XML element in the Custom XML Data part - is the Base64-encoded image data.

Figure 7.9. Picture

Picture

Attributes:

  • binding

    See generic attributes.

  • editable

    See generic attributes.

  • locked

    See generic attributes.

  • title

    See generic attributes. (The default value is Picture).

Content model:

(sdt:image-data)?

3.8. sdt:image-data

This element specifies the initial value of an sdt:picture element. It contains the Base64-encoded image data to be initially displayed in the picture SDT. If this element is omitted an image placeholder will be displayed. This placeholder includes a button to open an image selection dialog.

Attributes:

  • format

    This attribute specifies the image data format, in the form of a MIME type. Supported formats are GIF (image/gif), JPEG (image/jpeg) and PNG (image/png). This attribute is required. (The sdt:image-data element is ignored if this attribute is omitted.)

Content model:

#PCDATA

3.9. sdt:configuration

This element specifies optional parameters related to the Custom XML Data part. If this element is present in the XSL-FO tree it must occur before the first fo:page-sequence object.

Attributes:

  • custom-xml-template

    This 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. The URL is resolved by XFC using its current URI resolver.

  • prefix-mappings

    This attribute specifies the mapping of namespace prefixes used in XPath expressions that identify an element in a Custom XML Data template. The attribute value is a list of namespace declarations separated by white space. This attribute is required if the Custom XML Data template makes use of namespaces. For instance, consider the XML template below:

    <?xml version="1.0" encoding="UTF-8"?>
    <order xmlns="http://www.xmlmind.com/ns/order">
      <product>
        <reference />
        <quantity />
      </product>
    </order>

    As this template contains a namespace declaration, names in XPath expressions that identify an element in the template should be qualified. For this purpose one would set the prefix-mappings attribute and use the so declared namespace prefix to qualify element names in XPath expressions, as shown below.

    <sdt:configuration
      custom-xml-template="custom.xml"
      prefix-mappings="xmlns:ns=&quot;http://www.xmlmind.com/ns&quot;/order" />
    <sdt:text-field binding="/ns:order/ns:product/ns:reference"
      prompt="[Enter product reference.]" title="Reference" />

Content model:

EMPTY