Using the Mozilla JavaScript interface to XSL Transformations
by Mike Hearn, 27th November 2002This document describes the JavaScript interface in Mozilla 1.2 and up to the XSLT Processing Engine (TransforMiiX). Note, this does not apply to previous releases of Mozilla or Mozilla based browsers, which expose a obsolete interface.
To start, you need to create an XSLTProcessor object:
var processor = new XSLTProcessor();
Before you can use it, you must import a stylesheet with the importStylesheet() function. This has 1 parameter, which is the DOM Node of the stylesheet to import - note that the import is live, meaning that if you alter the stylesheet DOM after importing it, this will be reflected in the processing. It is however recommended to use stylesheet parameters instead of modifying the DOM. This is usually easier and can give better performance.
var testTransform = document.implementation.createDocument("", "test", null);
// just an example to get a transform into a script as a DOM
// XMLDocument.load is asynchronous, so all processing happens in the
// onload handler
testTransform.addEventListener("load", onload, false);
testTransform.load("test-transform.xml");
function onload() {
processor.importStylesheet(testTransform);
}
importStylesheet requires 1 argument, a DOM Node. If that node is a document node, you can pass in a full XSL Transform or a literal result element transform, otherwise it must be an xsl:stylesheet or xsl:transform element.
Then you can call the
transformToDocument() or transformToFragment()
methods. transformToDocument() takes 1 argument, the source node to transform, and returns a new DOM Document with the results of the transformation:
var newDocument = processor.transformToDocument(domToBeTransformed);
The resultant object is an HTMLDocument if the output method of the stylesheet is HTML, an XMLDocument for XML and for output method text an XMLDocument with a single root element <transformiix:result> with the text as a child.
You can also use transformToFragment() which will return a DOM DocumentFragment node. This is handy because appending a fragment to another node transparently appends all the children of that fragment, and the fragment itself is not merged. Fragments are therefore useful for moving nodes around and storing them without the overhead of a full document object. transformToFragment takes 2 arguments: the source document to be transformed (as above) and the a Document object that will own the fragment (all fragments must be owned by a document).
var ownerDocument = document.implementation.createDocument("", "test", null);
var newFragment = processor.transformToFragment(domToBeTransformed, ownerDocument);
transformToFragment will only produce HTML DOM objects if the owner document is itself an HTMLDocument, or if the output method of the stylesheet is HTML. It will not produce an HTML DOM objects if only the toplevel element of the result is <html> as transformToFragment is rarely used to create this element. If you want to override this, you can set the output method normally in the standard way.
You can control parameters for the stylesheet using the setParameter, getParameter and removeParameter methods. These all take a namespace URI and a local name as the first two parameters, with setParameter taking a 3rd - the value of the parameter to be set.
The XSLTProcessor object also implements a reset() method, which can be used to remove all stylesheets and parameters then put the processor back into its initial state. Note: this method is not implemented in the Mozilla 1.2 release.
Links:
>> The
MSDN page on the Internet Explorer implementation of this technology
>> The nsIXMLProcessor IDL file: this will always reflect the actual implementation of the XSLTProcessor object
>> The nsIXMLProcessorObsolete IDL file: the js interface in previous versions of Mozilla, obsolete
>> The nsIXMLProcessor IDL file: this will always reflect the actual implementation of the XSLTProcessor object
>> The nsIXMLProcessorObsolete IDL file: the js interface in previous versions of Mozilla, obsolete