Running Saxon

XSLT 2.0 transforms can be started from Saxon-CE in various ways to suit your requirement. This section provides an overview of the different transform methods along with links to more detailed documentation.

XML-Stylesheet Processing-Instruction

The first method employs a standard <?xml-stylesheet?> processing-instruction in the prolog of an XML document, as shown below:

<?xml-stylesheet type="text/xsl" href="sample.boot.xsl"?> <dt:data-set xmlns:dt=""> <dt:rows name="test-data"> ... </dt:data-set>

This provides the easiest upgrade from existing XSLT 1.0 applications. Because the processing instruction is read by the browser, not by Saxon, it can't load the XSLT 2.0 stylesheet directly. Instead, the href pseudo-attribute references a small XSLT 1.0 boot stylesheet, which then 'bootstraps' the Saxon processor. The boot stylesheet is not executed by Saxon-CE, but by the browser's built-in XSLT 1.0 processor. It uses JavaScript literal object properties, such as stylesheet: to set the URL of the actual XSLT 2.0 stylesheet to run (a sample is included in the samples directory in the Saxon-CE download).

Loading Saxon-CE

The XML processing-instruction described above exploits a 'boot' stylesheet to load Saxon-CE. When initiating an XSLT transform using the alternative methods described below, you first need to load Saxon-CE using a standard JavaScript script element within the HTML head or body elements:

<script type="text/javascript" language="javascript" src="../Saxonce/Saxonce.nocache.js"></script>

Note on using JavaScript to run XSLT on page-load

The Saxon-CE module is loaded using deferred loading. When executing a transform on page-load using JavaScript it's important that JavaScript API calls are initiated from within a user-declared onSaxonLoad function. This is to ensure that Saxon-CE loads first:

var onSaxonLoad = function() { Saxon.requestXML('data.xml'); ... };

Using an XSLT 2.0 Script Element

You can use the XSLT Script Element when you only need to execute a single transform when the HTML page loads, and no XSLT parameters or configuration settings are required.

<script type="application/xslt+xml" language="xslt2.0" src="books.xsl" data-source="books.xml"></script>

Running XSLT from declarative JavaScript

This utilizes a single call to the run function in the Saxon namespace. This takes as its single argument a Command object containing a description of the transformation to be executed.

Use this when a bit more flexibility is required, such as the need to set XSLT parameters or dynamically select a stylesheet.

<script> var onSaxonLoad = function() { { stylesheet: "books.xsl", source: "books.xml" }); </script>

Running XSLT with low-level JavaScript calls

The is probably the best choice when running transforms from within existing JavaScript code or when integration with other JavaScript libraries is a priority. This also allows compiled stylesheets to be reused for subsequent transforms.

The JavaScript API for Saxon-CE gives access to all Saxon-CE's processing features and settings, plus utility functions for handling XML in general. It is useful when dynamic behavior, stylesheet caching, and interoperability with existing JavaScript libraries are important.

<script> var onSaxonLoad = function() { var xsl = Saxon.requestXML("books.xsl"); var xml = Saxon.requestXML("books.xml"); var proc = Saxon.newXSLT20Processor(xsl); proc.updateHTMLDocument(xml); }); </script>

Processing Tips

When using XSLT 1.0 in the browser, it is common to generate a complete HTML page as output from the transformation. With XSLT 2.0, a more effective technique is to write multiple fragments of HTML, using them to populate named portions of the HTML page. So the initial HTML page will generally contain a skeletal structure of elements such as div element, each with an id attribute, waiting to be populated by the stylesheet.