<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
    <title>HOWTO</title>
    <subtitle>Configure an External XSLT Transformer</subtitle>
    <abstract>
        <para>This article explains how to install and configure an external XSLT transformer in
            Oxygen XML Editor 3.0 or higher.</para>
    </abstract>
    <sect1>
        <title>Introduction</title>
        <para>Oxygen comes with several preconfigured XSLT transformers like <application>Apache
            Xalan</application>, <application>Saxon</application> and <application>MSXML</application>. Each is a processor able to
            interpret the instructions of an XSLT Stylesheet conforming to <ulink
                url="http://www.w3.org/TR/1999/REC-xslt-19991116">XSL Transformations Version 1.0
                W3C Recommendation</ulink>.</para>
        <para>To enable the use of other XSLT transformers - faster, providing special XSLT
            extensions or a newer versions of <application>Xalan</application> or
            <application>Saxon</application> - the user can integrate and use a preferred transformer
            without switching between Oxygen and a command line prompt at run time.</para>
    </sect1>
    <sect1>
        <title>Installation and Configuration</title>
        <para>The transformer we will be installing is <application>Saxon version 8.9 SA</application>.
            If you are installing a different transformer, please exchange names, syntax and
            parameters to match your application.</para>
        <para>Before you proceed, please ensure that you have copied and installed the new XSLT
            transformer as per the instructions of the vendor. It's also a good idea to test that it
            works from the command line or by using a utility that may have been provided by the vendor. </para>
        <para>There are two ways for configuring an external XSLT engine as XSLT transformer in
            Oxygen: as JAXP transformer invoked through the Java JAXP interface or as custom XSLT
            transformer invoked with a configurable command line. </para>
        <procedure>
            <title>Configuring an External XSLT Engine as JAXP Transformer</title>
            <step>
                <para>Exit Oxygen if it is started.</para>
            </step>
            <step>
                <para>Copy the JAR file(s) of the transformer (just <filename
                    class="devicefile">saxon8sa.jar</filename> in the case of <application>Saxon
                    8.9 SA</application>) to the <filename class="directory">lib</filename>
                    subdirectory of your Oxygen installation directory.</para>
            </step>
            <step>
                <para>Start Oxygen.</para>
            </step>
            <step>
                <para>From the main menu select 
                    <menuchoice>
                        <guimenu>Options</guimenu>
                        <guimenuitem>Preferences</guimenuitem>
                        <guimenuitem>XML</guimenuitem>
                        <guimenuitem>XSLT / FO / XQuery</guimenuitem>
                        <guimenuitem>XSLT</guimenuitem>
                    </menuchoice>. The XSLT preferences panel is displayed in the Preferences dialog. 
                </para>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="jaxp-transformer-panel.gif" format="GIF" scale="80"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
            </step>
            <step>
                <para>Enter the name of the transformer factory, 
                    <emphasis role="bold">com.saxonica.SchemaAwareTransformerFactory</emphasis> for
                    <application>Saxon 8.9 SA</application>, as the value of the <application>JAXP</application> property
                        <emphasis role="bold">javax.xml.transform.TransformerFactory</emphasis>.
                    Oxygen sets this value for the property and uses it next time it creates a JAXP
                    transformation. 
                </para>
            </step>
            <step>
                <para>
                    <action>Click</action> the <guibutton>OK</guibutton> button to save your changes
                    and return to the editor.</para>
            </step>
            <step>
                <para>Test the new XSLT transformer by configuring and running a transformation
                    scenario using the <application>JAXP</application> transformer.</para>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="scenario-JAXP-engine.gif" format="GIF"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
                <para>The processing messages and results will be shown in the Message Pane of the
                    editor. </para> 
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="saxon-8-messages.gif" format="GIF" scale="75"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
            </step>
        </procedure>
        <procedure>
            <title>Configuring an External XSLT Engine as Custom XSLT Engine</title>
            <step>
                <para>Start Oxygen if it is not started.</para>
            </step>
            <step>
                <para>Go to the Custom Engines preferences panel from menu
                    <menuchoice>
                        <guimenu>Options</guimenu>
                        <guimenuitem>Preferences</guimenuitem>
                        <guimenuitem>XML</guimenuitem>
                        <guimenuitem>XSLT / FO / XQuery</guimenuitem>
                        <guimenuitem>XSLT</guimenuitem>
                        <guimenuitem>Custom Engines</guimenuitem>
                    </menuchoice>
                    <screenshot>
                        <mediaobject>
                            <imageobject>
                                <imagedata fileref="custom-engines-panel.gif" format="GIF" scale="80"/>
                            </imageobject>
                        </mediaobject>
                    </screenshot>
                </para>
            </step>
            <step>
                <para>Press the <emphasis>New</emphasis> button to create a new custom XSLT engine. </para>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="create-custom-engine.gif" format="GIF"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
            </step>
            <step>
                <para>Complete the dialog by selecting <emphasis>XSLT</emphasis> in the
                    <emphasis>Engine type</emphasis> combo box, entering the name of the engine that
                    will appear in the scenario edit dialog, the output stream encoding, the error
                    stream encoding, a working directory (usually the directory where the custom
                    XSLT engine is installed) and a command line executed when the engine is applied
                    in a transformation scenario. The working directory and the command line can
                    include editor variables like ${cfd} (meaning current file dirrectory), ${pd}
                    (meaning project directory), ${xml} (meaning the input XML document configured
                    in the transformation scenario), ${out} (meaning the output file configured
                    in the transformation scenario), etc.
                </para>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="editor-variables.gif" format="GIF"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
            </step>
            <step>
                <para>
                    <action>Click</action> the <guibutton>OK</guibutton> button to save your changes
                    and return to the editor.</para>
            </step>
            <step>
                <para>Test the new XSLT transformer by configuring and running a transformation
                    scenario using the <application>Saxon 8.9 SA</application> transformer.</para>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="scenario-custom-engine.gif" format="GIF"/>
                        </imageobject>
                    </mediaobject>
                </screenshot>
            </step>
        </procedure>
    </sect1>
</article>

