Introduction

Converters are processors converting XML documents from one format to another. For example, the standard HTML converter documented below converts an XML document into an HTML document. This HTML document can then be sent to a web browser using the HTTP serializer, or attached to an email with the Email processor.

Converters typically have a data output containing the converted document.

Standard converters

The standard converters convert XML infosets (the XML documents that circulate in Orbeon Forms pipelines) into text according to standard output methods defined by the XSLT specification. They convert to the following formats:

• XML: a standard XML document
• HTML: a standard HTML document
• XHTML: a standard XHTML document
• Text: any text document

The resulting text is sent to the data output. It is embedded in an XML document as specified by the text document format.

Configuration

The configuration of the standard converters consists of the following optional elements:

Example:

<config>
    <content-type>text/html</content-type>
    <encoding>utf-8</encoding>
    <version>4.01</version>
    <public-doctype>-//W3C//DTD HTML 4.01//EN</public-doctype>
    <system-doctype>http://www.w3.org/TR/html4/strict.dtd</system-doctype>
    <indent-amount>4</indent-amount>
</config>

XML converter

The XML converter outputs an XML document conform to the XSLT xml semantic. By default, the output is indented with no spaces and encoded using the UTF-8 character set. The default MIME content type is application/xml. The following is a simple XML converter example:

<p:processor name="oxf:xml-converter">
    <p:input name="config">
        <config>
            <content-type>application/xml</content-type>
            <encoding>iso-8859-1</encoding>
            <version>1.0</version>
        </config>
    </p:input>
    <p:input name="data" href="oxf:/my-xml-document.xml"/>
    <p:output name="data" id="xml-document"/>
</p:processor>

This is an example of output produced by the XML converter:

<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" content-type="application/xml; charset=iso-8859-1">&lt;?xml version="1.0" encoding="iso-8859-1" standalone="no"?&gt; &lt;claim xmlns="http://orbeon.org/oxf/examples/bizdoc/claim"&gt; &lt;insured-info&gt; &lt;general-info&gt; &lt;name-info&gt; &lt;title-prefix&gt;Dr.&lt;/title-prefix&gt; &lt;last-name&gt;Doe&lt;/last-name&gt; &lt;first-name&gt;John&lt;/first-name&gt; &lt;title-suffix/&gt; &lt;/name-info&gt; &lt;address&gt; &lt;address-detail&gt; &lt;street-name&gt;N Columbus Dr.&lt;/street-name&gt; &lt;street-number&gt;511&lt;/street-number&gt; &lt;unit-number/&gt; &lt;/address-detail&gt; &lt;city&gt;Chicago&lt;/city&gt; &lt;state-province&gt;IL&lt;/state-province&gt; &lt;postal-code&gt;60611&lt;/postal-code&gt; &lt;country&gt;USA&lt;/country&gt; &lt;email&gt;jdoe@acme.org&lt;/email&gt; &lt;/address&gt; &lt;/general-info&gt; &lt;person-info&gt; &lt;gender-code&gt;M&lt;/gender-code&gt; &lt;birth-date&gt;1972-10-01&lt;/birth-date&gt; &lt;marital-status-code&gt;C&lt;/marital-status-code&gt; &lt;occupation&gt;Manager&lt;/occupation&gt; &lt;/person-info&gt; &lt;family-info&gt; &lt;children&gt; &lt;child&gt; &lt;birth-date&gt;2003-02-02&lt;/birth-date&gt; &lt;first-name&gt;Marco&lt;/first-name&gt; &lt;/child&gt; &lt;child&gt; &lt;birth-date/&gt; &lt;first-name/&gt; &lt;/child&gt; &lt;/children&gt; &lt;comments&gt;No comments at this point!&lt;/comments&gt; &lt;/family-info&gt; &lt;claim-info&gt; &lt;accident-type&gt;FOOT&lt;/accident-type&gt; &lt;accident-date&gt;2004-07-06&lt;/accident-date&gt; &lt;rate/&gt; &lt;/claim-info&gt; &lt;/insured-info&gt; &lt;/claim&gt;</document>

HTML converter

The HTML converter outputs an HTML document conform to the XSLT html semantic. By default, the doctype is set to HTML 4.0 Transitional and the content is indented with no space and encoded using the UTF-8 character set. The default content type is text/html. The following is a simple HTML converter example:

<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:html-converter">
    <p:input name="config">
        <config>
            <content-type>text/html</content-type>
            <encoding>iso-8859-1</encoding>
            <public-doctype>-//W3C//DTD HTML 4.01 Transitional//EN</public-doctype>
            <version>4.01</version>
        </config>
    </p:input>
    <p:input name="data">
        <html>
            <head>
                <title>My HTML document</title>
            </head>
            <body>
                <p>
                    This is the content of the HTML document.
                </p>
            </body>
        </html>
    </p:input>
    <p:output name="data" id="html-document"/>
</p:processor>

This is an example of output produced by the HTML converter:

<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" content-type="text/html; charset=iso-8859-1">
    &lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"&gt;
      &lt;html&gt;
        &lt;head&gt;
          &lt;title&gt;My HTML document&lt;/title&gt;
        &lt;/head&gt;
      &lt;body&gt;
        &lt;p&gt;
          This is the content of the HTML document.
        &lt;/p&gt;
      &lt;/body&gt;
    &lt;/html&gt;
</document>

Text converter

The Text converter outputs a text document conform to the XSLT text semantic. By default, the output is encoded using the UTF-8 character set. This serializer is typically useful for pipelines generating Comma Separated Value (CSV) files. The default content type is text/plain. The following is a simple Text converter example:

<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:text-converter">
    <p:input name="config">
        <config/>
    </p:input>
    <p:input name="data">
        <document>
            This is just plain text. It will be output without the <em>text</em> and <em>em</em> elements.
        </document>
    </p:input>
    <p:output name="data" id="text-document"/>
</p:processor>

This is an example of output produced by the Text converter:

<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" content-type="text/plain; charset=utf-8">
    This is just plain text. It will be output without the text and em
    elements.
</document>

Custom serializer classes

Built-in custom serializers

To-XML converter

The To-XML Converter produces a parsed XML document from a binary document format.

Configuration

The data input of the To-XML Converter follows the binary document format. Its data output is an XML document.

The mandatory config input consists of the following optional elements:

Example

This is an example of use:

<p:config xmlns:p="http://www.orbeon.com/oxf/pipeline">

    <p:param type="output" name="data"/>

    <!-- Read an XSLT document and output it in binary format -->
    <p:processor name="oxf:url-generator">
        <p:input name="config">
            <config>
                <url>parsing-view.xsl</url>
                <mode>binary</mode>
            </config>
        </p:input>
        <p:output name="data" id="xml-file-as-binary"/>
    </p:processor>

    <!-- Serialize back the binary format to XML while performing XInclude -->
    <p:processor name="oxf:to-xml-converter">
        <p:input name="data" href="#xml-file-as-binary"/>
        <p:input name="config">
            <config>
                <handle-xinclude>true</handle-xinclude>
            </config>
        </p:input>
        <p:output name="data" ref="data"/>
    </p:processor>

</p:config>

Plain HTML/XHTML converters

XSL-FO converter

The XSL-FO Converter produces PDF documents from an XSL-FO description of the page. The default content type is application/pdf.

The resulting binary stream is sent to the data output. It is embedded in an XML document as specified by the binary document format.