<oXygen/> XML Editor User Guide

Transformation scenario

Before transforming the current edited XML document in <oXygen/> you must define a transformation scenario to apply to that document. A scenario is a set of values for various parameters defining a transformation. It is not related to any particular document but to a document type:

Scenarios that apply to XML files

Such a scenario contains the location of an XSLT stylesheet that is applied on the edited XML document and other transform parameters.

Scenarios that apply to XSL files

Such a scenario contains the location of an XML document that the edited XSL file is applied on and other transform parameters.

Builtin transformation scenarios

If the Apply Transformation Scenario toolbar button is pressed, currently there is no scenario associated with the edited document and the edited document contains a "xml-stylesheet" processing instruction reffering to a XSLT stylesheet (commonly used for display in Internet browsers), then <oXygen/> will prompt the user and offer the option to associate the document with a default scenario containing in the XSL URL field the URL from the href attribute of the processing instruction. This scenario will have the "Use xml-stylesheet declaration" checkbox set by default, will use Saxon as transformation engine, will perform no FO processing and will store the result in a file with the same URL as the edited document except the extension which will be changed to html. The name and path will be preserved because the output file name is specified with the help of two macros: ${cfd} and ${cfn}.

<oXygen/> comes with preconfigured builtin scenarios for usual transformations that enable the user to obtain quickly the desired output: associate one of the builtin scenarios with the current edited document and then apply the scenario with just one click.

Defining a new transformation scenario

The Configure Scenario dialog is used to associate a scenario from the list of all scenarios with the edited document by selecting an entry from the list. The dialog is opened by pressing the Configure Transformation Scenario button on the toolbar of the document view. Once selected the scenario will be applied with only one click on the Apply Transformation button on the same toolbar. Pressing the Apply Transformation button before associating a scenario with the edited document will invoke first the Configure Scenario dialog and then apply the selected scenario.

Open the Configure Transformation dialog by selecting Document->Configure transformation scenario (Ctrl+Shift+C).

Figure 5.1. The Configure Transformation Dialog

The Configure Transformation Dialog

Complete the dialog as follows:

XSLT Tab

Use the XSLT tab to specify an input XSL file to be used for the transformation. You can also add XSLT parameters and append header and footer URL's to be included in the transformation. To apply a cascade of stylesheets the user can set the list of stylesheets applied after the stylesheet from the XSL URL field in the dialog displayed after pressing the "Cascade Stylesheets" button. The user can choose between Xalan and Saxon when configuring the transformation. Saxon is faster on Docbook stylesheets.

FOP Tab

Use the FOP tab to enable/disable use of FOP during a transformation. FOP input may be provided from the XSLT output or the edited document source. <oXygen/> is supplied with the Apache FOP, but supports definition and use of any third party processor. Default output method is set to use PDF , but PS and TXT are also configured. You may add and define any method supported by your FOP.

Output Tab

Use the Output Tab to specify the output path where target output files will be saved. When performing an XHTML transformation the relative path for image locations must be provided in order to ensure that image paths will be correctly resolved in order to be displayed in the output files. When using FOP this is not required as images will be embedded within the output PDF or PS. This option will therefore be disabled during FOP transformations.

The list of cascade stylesheets can be edited in the dialog opened by the button "Cascade Stylesheets".

Figure 5.2. Edit cascade stylesheets list dialog

Edit cascade stylesheets list dialog
Add

Adds a stylesheet in the "Cascade stylesheets" list using a file browser dialog , also you can type a macro in the file name field of the browser dialog. The name of the stylesheet will be added in the list after the current selection.

New

Opens a dialog in which you can type the name of a stylesheet. The name is considerd relative to the URL of the current edited XML document. You can use macros in the name of the stylesheet. The name of the stylesheet will be added in the list after the current selection.

Remove

Deletes the selected stylesheet from the "Cascade stylesheets" list.

Open

Opens the selected stylesheet in a separate view .

Up

Move the selected stylesheet up in the list.

Down

Move the selected stylesheet down in the list.

In the fields reserved for: input URL (XSL URL or XML URL, depending on scenario type), header URL, footer URL, the URLs in the list of cascade stylesheets, image base URL, the user can use the following macros:

${frameworks}

the path of the frameworks subdirectory of the <oXygen/> install directory

${home}

the path of the user home directory

${cfdu}

current file directory url - the path of the current edited document up to the name of the parent directory as URL

${cfn}

current file name - the name of the current edited document without extension and parent directory

In the Save As field from the Output tab, the user can use the following macros:

${frameworks}

the path of the frameworks subdirectory of the <oXygen/> install directory

${home}

the path of the user home directory

${cfd}

current file directory - the path of the current edited document up to the name of the parent directory

${cfn}

current file name - the name of the current edited document without extension and parent directory

The macros defined here can also be used in the values set for the parameters of the transformation (e.g. base.dir).

Use the following procedure to create a scenario.

  1. Select Document->Configure transformation scenario (Ctrl+Shift+C) to open the Configure Transformation dialog.

  2. Click the Duplicate Scenario icon to the right of the top combo box to create a copy of the current "Scenario".

  3. Double-click in the Name field to select the exiting text.

  4. Type a new name.

  5. Click OK or Transform Now to save the "Scenario".

Exporting and importing the transformation scenarios

The option to Export Transformation Scenarios is used to store all the scenarios in a separate file , a properties file. In this file will also be saved the associations between document urls and scenarios. The saved urls are absolute . You can load the saved scenarios using Import Transformation Scenarios option. All the imported scenarios will have added to the name the word 'import'.

  • The action Options->Import transformation scenarios loads a properties file with scenarios.

  • The action Options->Export transformation scenarios stores all the scenarios in a separate file , a properties file.