| 3. Reference Material | ||
|---|---|---|
 | Chapter 7. XSL-FO extension for Office Open XML | |
| 3. Reference Material | ||
|---|---|---|
| | Chapter 7. XSL-FO extension for Office Open XML | |
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:
sdt:text-field
sdt:drop-down-list
sdt:combo-box
sdt:date
sdt:picture
These are inline-level elements that may appear anywhere inline-level Formatting Objects are allowed.
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.
This element is converted to a plain text SDT, which provides the functionality of a basic 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
This element is converted to a drop-down list SDT, which provides the ability to select a single value from a predefined 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)+
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
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)+
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.
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:
| Variable | Expanded Value |
|---|---|
| %D | day of month (01-31) |
| %M | month (01-12) |
| %Y | year (4 digits) |
| %y | year (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
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.
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)?
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
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="http://www.xmlmind.com/ns"/order" />
<sdt:text-field binding="/ns:order/ns:product/ns:reference" prompt="[Enter product reference.]" title="Reference" />
Content model:
EMPTY
| |  | |
| 2. How it works |  |
