<oo>→<dh> Digital humanities

Introduction

In addition to the <oXygen/> XSLT debugger mode, there are alternative ways to transform XML files with XSLT that developers apply in projects, including some that can transform more than one XML file at a time.

Client-side transformation with XSLT

One procedure involves client-side transformation, or transforming within a web browser. To implement client-side transformation you insert a line into the XML document that tells the browser to use a particular XSLT stylesheet to transform the document in order to render it for viewing. This is similar to associating a CSS stylesheet with an XML document, and it has at least two related advantages over having the developer run the transformation and upload the HTML output. Transforming the XML to HTML before uploading is an extra step, and it has to be repeated every time the author revises the XML, so the first advantage is cutting out this extra stage. The second advantage is that because the user is downloading the XML and transforming it in the browser, the transformation is applied automatically in real time to the XML, so there is no danger of updating the XML but forgetting to rerun the transformation and upload the correspondingly revised HTML.

The principal disadvantage of client-side (in-the browser) XSLT transformation is that web browsers (as of this writing in 2015) do not evenly support XSLT rendering and none of the major browsers supports XSLT 2.0 which means that you cannot be confident of reliable output and you have to confine yourself to XSLT 1.0 features and functionality. Furthermore, associating the XSLT with the XML makes the most sense if the XML is going to be transformed only in one way, such as to create a reading text in HTML. If you want to transform your XML in more than one way, you can’t associate two stylesheets with the same XML and have them operate independently. For a comparative review of browsers in client-side transformation, see Julian Reschke’s Test cases for XSLT support in browsers and Yegor Bugayenko’s survey of options for client-side rendering. Finally, Saxon CE is a JavaScript library that can provide XSLT 2.0 support for client-side transformations in any browser, but it imposes a delay on first download and requires that your XSLT be structured in a way that matches the Saxon CE protocols.

If you decide to use client-side (in-browser) transformation with XSLT, the easiest way to associate your XSLT stylesheet with your XML document instance is to let <oXygen> help you. As is illustrated below, with your XML document open in <oXygen>, go to the Document menu and select XML Document, then Associate XSLT/CSS Stylesheet. Change to the XSLT tab, click on the little folder icon to the right of the text input box, and pick your XSLT file. <oXygen/> will write a stylesheet association line into your XML, and when you next load the XML file into a web browser, you should see your XML styled according to your XSLT.

Developer transformation with XSLT: transformation scenarioes

As an alternative to client-side transformation, you can perform the transformation yourself and upload just the HTML (or other) output of the stylesheet transformation, instead of the raw XML together with the stylesheet. This has the advantage of letting you use XSLT 2.0 features, but it the disadvantage is that you have to remember to regenerate the output whenever you change the XML. Because we often use XSLT 2.0 features and often transform our XML in more than one way, this is the strategy we use most often in our own projects. It’s a little more complicated for the developer (it involves more clicking), but not terribly so, and here, too, you can let <oXygen/> help you.

You already know how to transform an XML document with XSLT in the <oXygen/> XSLT debugger, and how to save the output of the transformation so that you can upload it to your project site. This isn’t necessarily the best way to create HTML output, though. The XSLT debugger interface excels at—well—XSLT debugging, but if know your XSLT is okay (doesn’t require debugging) and you just want to transform your XML, you may find it easier to do that by configuring an <oXygen/> transformation scenario.

As is illustrated below, start by going to that same Document menu and going to Transformation and then Configure Transformation Scenario. Any saved transformations will be listed, but to create a new one you ignore those and click instead on New and from Scenario type select XML transformation with XSLT. The New scenario dialog, illustrated below, then opens and asks for additional information.

You’ll need to specify both your XML and XSL files in the first tab (labeled XSLT), along with the XSLT transformer you want to use. Although <oXygen/> may try to guess which files and transformer to use based on which file was in focus when you opened the menu, it’s safer and easier in the long run to specify all of this information explicitly. If you’re using XSLT 2.0 features, we’d recommend selecting either Saxon PE or Saxon HE as the transformer. To the right of the XML URL and XSL URL boxes you can click on the little folder icons and navigate to the XML and XSLT files you want to use for the transformation. <oXygen/> will let you set one or both to Current file and a few other variable values, but if you accidentally have the wrong files in focus when you do that, you’ll get the wrong result, so it’s safest just to specify both files fully. In the Output tab you need to specify the location and name of the HTML file you want to create, and you can select to view the file in <oXygen/> and/or in your Internet browser if you want (see the green highlighting in the illustration below). When you’re all done, hit OK, run the transformation, and then upload your new HTML file to your project directory on the server and link to it, so that users can access it easily.

If, in the future, you wish to run this scenario again, simply navigate the menus again and select Apply Transformation Scenario instead of Configure Transformation Scenario (although you can actually do it from either, as noted above), and select the scenario you wish to run. You’ll need to re-upload your HTML file, if you regenerate it, to replace the old version on the server.

Batch processing multiple XML files with XSLT

Project developers frequently need to transform many XML files at once. One common situation is that you are delivering a large number of files with similar markup (such as a poetry collection), you want them all rendered similarly, and you change your rendering preferences. In this case you’ll want to modify the XSLT you use to generate the HTML versions of the poems and then transform them all. Loading each one separately into <oXygen/> and transforming it in the XSLT debugger or by using the methods above means a lot of repetitive actions on your part, and what you’d prefer is to run a single transformation that gets applied to each of the files without your having to specify them one by one.

The <oXygen/> Project menu provides a helpful tool for batch processing. The following list describes how to use that menu to set up a simple batch transformation over a group of XML files stored in a local directory on your computer.

• Go to the Project menu and create a new project by associating it with a file directory you’ve made and giving the project a name (<oXygen/> will append the extension .xpr to the project name and save it as a file on your disk). Select Show project view on that Project menu, to bring it up on the left side of the screen
• In the Project view, select the new project (right-click or command-click) to bring up a list of menu commands. Select the command to Add files from your directory. As you add the files, you will see them populate the area beneath the Project.xpr. You can choose all of the files in the directory at once, or just a selection of some of them.
• The next step is to configure a transformation scenarios for the project (what you did in the preceding section was configure a transformation scenario for just one file, but now you’re going to do that all at once for all files in the project). This is a little tricky because you can’t just select the project and configure a transformation scenario on it as a directory. You have to select the files you wish to transform (or all the files) inside the project first, and then right click, select Transformation Scenarios, and configure a scenario for those files (that is, for the project).
• Even when you tell <oXygen/> to transform an entire directory of files, it transforms them one by one, so you need to tell it to transform not all of the files in the directory, but each of the files in the directory. <oXygen/> supports this type of configuration through special variables you can use to identify the files you have selected and to designate a directory to hold the output files from the transformations. Here is how to configure the transformation scenario to handle a set of files in a directory:
  • With one or more files selected in the project view, set the XML URL for the input file to ${currentFileURL} It’s crucial that you select one or more files first because if you don’t do that, even with the Project View open, ${currentFileURL} defaults to an <oXygen/> program directory and sends an error message when it can’t find any files to process there. If you’ve selected files in your project, though, <oXygen/> will use them correctly.
  • To the right of the XML URL window, click the icon furthest to the right of the three (to the right of the folder icon). It looks like a piece of paper (for a document) with a green arrow pointing to the right. If the variable is properly associated with your project files, you’ll pull up a specific file in the <oXygen/> editing window. If not, you will see an error message indicating that the specified file doesn’t exist.
  • The XSL URL can be an absolute file path to any directory holding your XSLT stylesheet: Mine, for example, is currently set to file:/C:/dhXSLT/Web2Web.xsl.
  • You need a place to store the output, and for configuration purposes it is easiest to save it in a directory inside your Project directory. We will use <oXygen/> variables again here, but they will be different this time. If you are storing your output in a subdirectory of the project, here is how to identify its location: ${pdu}/output/${cfne} Here, ${pdu} refers to the Project URL, “output” is a new directory I created to hold the output, and ${cfne} means current file name with its extension. (If you want to remove the extension, the variable is {$cfn}; this lets you add a different extension, so that, for example, you can transform filename.xml to filename.xhtml by setting the output to ${pdu}/output/${cfn}.xhtml.
• Save the scenario. Select one or all of the files in the directory, and go to Apply Transformation Scenarios, and you can see the transformation working in the bottom message pane for each file.
• When you have completed the batch transformation, open and review the files in your output folder. You can save any schema files you are using in that folder and even create a new <oXygen/> Project for the output files, in case you’d like to transform them further. The Project View lets you open all files to review them side by side. Follow the options in the Project view menu to validate all the files at once.

Transformations at the command line

Configuring a transformation scenario for a single XML file, and especially for batch transformation of multiple files, avoids the overhead of going through the <oXygen/> debugger. But because the transformation is actually performed by the Saxon XSLT engine operating within <oXygen/>, and not by <oXygen/> itself, we can simplify the process even further by cutting <oXygen/> out of the process altogether.

Saxon is available in three versions: EE (enterprise edition), PE (professional edition), and HE (home edition) (see the feature matrix to compare them). All three are bundled with <oXygen/> and any of the three can be used in the <oXygen/> XSLT debugger or in a transformation scenario. EE and PE are commercial products that you can purchase to use outside <oXygen/>; HE is free and open source, so you can download and use it outside <oXygen/> without cost. Although HE has the fewest features of the three, we’ve been able to use it effectively in our projects, and if you’d like to experiment with command-line XSLT transformation, you can download it at http://sourceforge.net/projects/saxon/files/Saxon-HE/.

Instructions for using Saxon at the command line are at http://www.saxonica.com/documentation/index.html#!using-xsl/commandline. The short version is:

java  -jar /path-to-saxon/saxon9he.jar -s:input.xml -xsl:stylesheet.xsl -o:output.xml

Replace the filenames with the names of your real files. To transform an entire directory of files, you can specify the directory names as arguments to the -s: and -o: switches.