JavaScript API

The JavaScript API for Saxon-CE is loaded using a standard HTML script element:

]]>

When using this API, it's important to ensure the Saxon-CE library is loaded first. The global onSaxonLoad callback function is provided to facilitate this during an HTML page load. Saxon-CE will make a call to this once it has loaded.

The API is centred around 2 principal objects:

XSLT20Processor

XSLT20Processor is modeled on the JavaScript XSLTProcessor API as implemented by Opera, Mozilla, Safari and Chrome browsers (Sarissa provides a wrapper compatible with Internet Explorer). It provides a set of methods used to initiate XSLT transforms on XML or direct XSLT-based HTML updates. This standard API has been extended to: (a) access functionality new to XSLT 2.0, (b) provide extra features specific to HTML processing, and (c) support asynchronous processing.

Saxon

The Saxon object provides a factory method for instantiating XSLT20Processor and a run function for invoking transforms more declaratively by using a JavaScript literal object to describe the transform. It also includes a small set of utility functions for managing XML resources and controlling the logging of messages from XSLT20Processor object instances.

Links to all JavaScript API Sections:

Command

The Command object is used exclusively by the Saxon object's run function. It's designed to be used as a JavaScript literal object and effectively wraps the Saxon-CE API with a set of properties so you can run an XSLT transform on an HTML page in a more declarative way.

If you need to include a namespace in an XSLT parameter name, use the Clark notation: {uri}local - for example {http://saxonica.com/units}mass-kg

In the properties listed below, only stylesheet (shown in italics) is mandatory, but either initialTemplate or source must also be set, to ensure that the stylesheet has an entry point.

Properties

Property	Type	Description
errorHandler	Function	The callback function for handling processing errors.
initialMode	String	The initial mode for the transform
initialTemplate	String	The initial template for the transform
logLevel	String	Sets the error and event logging threshold.
method	String	The transform method to use [Default: updateHTMLDocument]
parameters	Map:Name→Value	XSLT parameters are set from the matching values of properties of the parameters object.
source	String\|Document	The XML document source for the transform
stylesheet	String\|Document	Sets the stylesheet for the transform
success	Function	The success callback function - called after a transform.

Notes

An example of how the literal Command object can be used with the Saxon run method is shown below. This sample also shows how to use the onSaxonLoad function to ensure the Saxon-CE library loads fully before any JavaScript API calls are made on the library.

Saxon

This is used as a static object, providing a set of utility functions for:

Creating new instances of the XSLT20Processor object
Initiating a simple XSLT transform declaratively
Working with XML resources
Configuration and house-keeping tasks

Functions

Function	Description
`getErrorHandler()`	Returns a reference to the function set as the Saxon error handler.
`getLogLevel()`	Returns the level at which events, warning and errors are logged.
`getVersion()`	Returns the version number of the Saxon-CE processor.
`newXSLT20Processor(xslt)`	The factory method for creating a new XSLT20Processor object.
`parseXML(arg)`	Returns a new XML document object created from the lexical XML String passed as an argument.
`requestXML(uri)`	Emulates an XMLHTTPRequest, effectively returning an XML document object.
`run(cmd)`	Uses JavaScript literal object properties to execute an XSLT transform.
`serializeXML(xml)`	Returns a String that represents a serialization of the XML Node argument.
`setErrorHandler(handler)`	Sets a callback function to allow your own code to manage events and errors occurring in the XSLT20Processor object.
`setLogLevel(level)`	Sets the level at which events, warning and errors are logged.

getErrorHandler

getErrorHandler() → Function

Returns a reference to the function set as the Saxon error handler.

There are no arguments
Result		Function

Details

This function corresponds to the setErrorHandler function and returns null if no error handler was set.

getLogLevel

getLogLevel() → String

Returns the level at which events, warning and errors are logged.

There are no arguments
Result		String

Details

There are 7 logging levels, ranging from SEVERE to FINEST. See the Logging section fur further details.

Note that the log level is set using setLogLevel or by a logLevel URI argument.

getVersion

getVersion() → String

Returns the version number of the Saxon-CE processor.

There are no arguments
Result		String

Details

newXSLT20Processor

newXSLT20Processor($xslt as Document?) → XSLT20Processor

The factory method for creating a new XSLT20Processor object.

Arguments
	$xslt	Document?	The XML Document containing the stylesheet.
Result		XSLT20Processor

Details

The optional xslt argument is used to specify the stylesheet to be used when one of the transform functions of this object is called. The function, requestXML, provides a cross-browser method for getting a Document instance of the stylesheet.

If the xslt argument is null when XSLT20Procssor is initialised using this function, the importStylesheet function should always be called first, before initiating a transform.

It's possible to use a number of XSLT20Processor instances. This may be useful either when you want to exploit a number of previously compiled stylesheets, or when working with different HTML target pages (events from the host page are broadcast to all processors that have stylesheets with ixsl:event templates).

parseXML

parseXML($arg as String) → Document

Returns a new XML document object created from the lexical XML String passed as an argument.

Arguments
	$arg	String	The XML string to be converted.
Result		Document

Details

This is a cross-browser method for parsing an XML string and converting it to an XML document object.

requestXML

requestXML($uri as String) → Document

Emulates an XMLHTTPRequest, effectively returning an XML document object.

Arguments
	$uri	String	The URI of the document to fetch
Result		Document

Details

This method creates a placeholder for a document object that can be used as an argument wherever a Document object is required by an API method, such as transformToDocument(). The use of such a placeholder allows Saxon-CE to determine whether to retrieve the document synchonously or asynchronously, depending on the context in which it is used.

Note: Typically, XML resources that are used as XSLT stylesheets are fetched synchronously, whilst those loaded as data are fetched asynchronously while the XSLT compiles.

run

run($cmd as Command?) → XSLT20Processor

Uses JavaScript literal object properties to execute an XSLT transform.

Arguments
	$cmd	Command?	The URI of the stylesheet.
Result		XSLT20Processor

Details

A call to this function uses a single Command object parameter to describe the XSLT transform to run. The Command object is designed to be used as JavaScript literal:

This function returns a newly created XSLT20Processor object. Use this object's getResultDocument and getResultDocuments functions to get any output results from the tranform. Note that the principal output document is returned by a call to getResultDocumemt with no parameter value.

The run method serves as a wrapper for the 3 lower-level transform calls of the API: transformToDocument, transformToFragment and updateHTMLDocument. The latter of these is the default function, use the method property with the function name to specify an alternative transform.

serializeXML

serializeXML($xml as Node) → String

Returns a String that represents a serialization of the XML Node argument.

Arguments
	$xml	Node	The Node to serialize
Result		String

Details

This method provides a simple cross-browser wrapper for serialising a XML DOM node. Results may therefore vary according to the host browser used. For example, when serialising a DocumentFragment containing a number of top-level elements, Internet Explorer only serializes the first element.

setErrorHandler

setErrorHandler($handler as Function) →

Sets a callback function to allow your own code to manage events and errors occurring in the XSLT20Processor object.

Arguments
	$handler	Function	The function to which callbacks will be made on events or errors
Result

Details

The error and event handling capability this callback provides is for use with the Debug variant of Saxon only. The threshold for this callback is controlled by the Logging setLogLevel method, or a URI argument - see the Logging section for further details.

The $handler function argument signature should hava a single error argument. The error object which is passed in the callback can then be used to get details on the error or event. It has 3 properties: message, level and time. If no error handler is set, any JavaScript or XSLT exceptions are thrown so that your code can manage them.

Sample JavaScript code:

0) { window.alert(errors.toString()); } } // ------ DECLARE ERROR HANDLER -------- function handler(saxonError) { errors.push(saxonError.message + " " + saxonError.level + " " + saxonError.time); } ]]>

setLogLevel

setLogLevel($level as String?) →

Sets the level at which events, warning and errors are logged.

Arguments
	$level	String?	The threshold at which events or errors are logged.
Result

Details

There are 7 logging levels, ranging from SEVERE to FINEST. See the Logging section fur further details.

XSLT20Processor

The XSLT20Processor object provides the various functions used to perform an XSLT 2.0 transform. This section describes all the available functions, but the following (along with the object constructor) are probably going to be used most often:

1. Configure:	setParameter	setInitialTemplate	setMode
2. Transform:	updateHTMLDocument	transformToDocument	transformToFragment

When using the API on page-load, you should ensure Saxon-CE is loaded first by including your code within the global onSaxonLoad function. This function is called as soon as the HTML page has loaded and Saxon-CE has been initialized.

XSLT20Processor instances are created using the newXSLT20Processor factory method of the static Saxon object (which also provides a set of XML utility functions along with functions for controlling error logging).

Functions

Function	Description
`clearParameters()`	Removes all parameters set for the XSLT20Processor instance.
`getInitialMode()`	Gets the initial mode set for the XSLT transform.
`getInitialTemplate()`	Gets the name set for the XSLT transform initial template
`getParameter(namespace, name)`	Gets the value of the named XSLT transform parameter.
`getResultDocument(uri)`	Returns a result document created by the xsl:result-document instruction
`getResultDocuments()`	Returns any array of result document URIs that were output by the previous XSLT transform.
`getSuccess()`	Returns the callback function set by setSuccess
`importStylesheet(xsl)`	Sets the stylesheet to be used for an XSLT transform
`removeParameter(name)`	Removes the named parameter.
`reset()`	Resets the XSLT20Processor object to its original state.
`setBaseOutputURI(uri)`	Set the base URI for resolving output URIs from an XSLT transform
`setInitialMode(name)`	Sets the name for the initial mode to be called for the XSLT transform
`setInitialTemplate(name)`	Sets the name for the initial template to be called for the XSLT transform
`setParameter(namespace, name, value)`	Sets named parameters for the XSLT transform
`setSuccess(callback)`	Following a transform, a callback is made to this function
`transformToDocument(source)`	Returns the result of an XSLT transform as a Document object.
`transformToFragment(source, ownerDocument)`	Returns the result of an XSLT transform as a DocumentFragment object.
`transformToHTMLFragment(source, ownerDocument)`	Returns the result of an XSLT transform as one or more HTML DocumentFragment objects.
`updateHTMLDocument(source, target)`	Initiates an XSLT transform on an existing HTML document.

clearParameters

clearParameters() →

Removes all parameters set for the XSLT20Processor instance.

There are no arguments
Result

Details

See: setParameter and getParameter

getInitialMode

getInitialMode() → String

Gets the initial mode set for the XSLT transform.

There are no arguments
Result		String

Details

If the returned name has a namespace, then the result is formatted using the James-Clark notation: {uri}local.

getInitialTemplate

getInitialTemplate() → String

Gets the name set for the XSLT transform initial template

There are no arguments
Result		String

Details

If the returned name has a namespace, then the James-Clark notation is used: {uri}local.

getParameter

getParameter($namespace as String, $name as String) → Object

Gets the value of the named XSLT transform parameter.

Arguments
	$namespace	String	The namespace for the parameter name or null
	$name	String	The parameter name
Result		Object

Details

This is the counterpart to the setParameter method

getResultDocument

getResultDocument($uri as String) → Document|DocumentFragment

Returns a result document created by the xsl:result-document instruction

Arguments
	$uri	String	The URI of the result document
Result		Document\|DocumentFragment

Details

Result documents created when calling the XSLT20Processor functions transformToDocument or transformToFragment each have a unique URI. The uri parameter identifies the specific document to return, the result is null if no result document was output with a matching URI.

When getResultDocument is called with no parameter or a null or empty-string parameter value, the principal output document, if any, is returned.

This function can be used in combination with GetResultDocuments() which returns a String array of all result document URIs from the last XSLT transform.

getResultDocuments

getResultDocuments() → String Array

Returns any array of result document URIs that were output by the previous XSLT transform.

There are no arguments
Result		String Array

Details

Note: You can use the getResultDocument(uri) function to get a reference to the Document or DocumentFragment identified by each URI.

getSuccess

getSuccess() → Function

Returns the callback function set by setSuccess

There are no arguments
Result		Function

Details

importStylesheet

importStylesheet($xsl as Document) →

Sets the stylesheet to be used for an XSLT transform

Arguments
	$xsl	Document	The XML Document containing the stylesheet to import
Result

Details

Note that the XSLT20Processor constructor can also be used to set the stylesheet.

removeParameter

removeParameter($name as String) →

Removes the named parameter.

Arguments
	$name	String	The parameter name
Result

Details

See: setParameter and getParameter

reset

reset() →

Resets the XSLT20Processor object to its original state.

There are no arguments
Result

Details

Clears the XSLT20Processor instance settings for parameters, imported stylesheet, initial template and initial mode

setBaseOutputURI

setBaseOutputURI($uri as String?) →

Set the base URI for resolving output URIs from an XSLT transform

Arguments
	$uri	String?	The base URI for output documents
Result

Details

If no uri is supplied, the base output uri is reset.

setInitialMode

setInitialMode($name as String) →

Sets the name for the initial mode to be called for the XSLT transform

Arguments
	$name	String	The mode name
Result

Details

To set a namespace-qualified name, use the James-Clark notation: {uri}local.

setInitialTemplate

setInitialTemplate($name as String) →

Sets the name for the initial template to be called for the XSLT transform

Arguments
	$name	String	The template name
Result

Details

To set a namespace-qualified name, use the James-Clark notation: {uri}local.

setParameter

setParameter($namespace as String, $name as String, $value as Object) → Void

Sets named parameters for the XSLT transform

Arguments
	$namespace	String	The namespace for the parameter name or null
	$name	String	The parameter name
	$value	Object	The parameter value
Result		Void

Details

Supplied parameter types may be String, Double, Node or Array. Array items may be any of these types, except Array.

Sample JavaScript code:

setSuccess

setSuccess($callback as Function) →

Following a transform, a callback is made to this function

Arguments
	$callback	Function	The callback function
Result

Details

The callback function has the signature success(proc) where proc is the instance of XSLT20Processor performing the transform.

If success is not set, then processing will be synchronous for calls to transformToDocument and transformToFragment. The updateHTMLDocument function can potentially always run asynchronously as it has no return values (it simply updates the target HTML document).

transformToDocument

transformToDocument($source as Node?) → Document

Returns the result of an XSLT transform as a Document object.

Arguments
	$source	Node?	The source document or node to be transformed.
Result		Document

Details

If no source document is supplied then an initialTemplate must be set.

transformToFragment

transformToFragment($source as Node?, $ownerDocument as Document?) → DocumentFragment

Returns the result of an XSLT transform as a DocumentFragment object.

Arguments
	$source	Node?	The source document or node to be transformed.
	$ownerDocument	Document?	The owner document for the fragment
Result		DocumentFragment

Details

If no source document is supplied then an initialTemplate must be set. A DocumentFragment is useful because it can be it allows a set of nodes to be appended to the DOM without a container element.

All DocumentFragments must have an owner document, if none is supplied as a parameter a new XML document is created for this purpose.

transformToHTMLFragment

transformToHTMLFragment($source as Node?, $ownerDocument as Document?) → DocumentFragment

Returns the result of an XSLT transform as one or more HTML DocumentFragment objects.

Arguments
	$source	Node?	The source document or node to be transformed
	$ownerDocument	Document?	The owner document for the HTML fragment
Result		DocumentFragment

Details

If no source document is supplied then an initialTemplate must be set. All DocumentFragments must have an owner document, if none is supplied as a parameter the owner is set to the host HTML document.

This function returns a collection of HTML fragments that can be appended directly to the DOM. Each returned fragment can contain a number of nodes, but can be appended to an HTML DOM element as a single node. The getResultDocument and getResultDocuments functions are used to retrieve each result fragment. Note that the updateHTMLDocument function provides similar functionality, but fragment updates are peformed entirely within the XSLT using the xsl:result-document instruction's href attribute to specify the target node for each result fragment.

updateHTMLDocument

updateHTMLDocument($source as Node?, $target as Document?) → String

Initiates an XSLT transform on an existing HTML document.

Arguments
	$source	Node?	The source document or node to be transformed
	$target	Document?	The HTML Document object to update
Result		String

Details

The initial template must be set (using setInitialTemplate) when the source parameter is null. If the target parameter value is null, then the host HTML page is the target for all output.

updateHTMLDocument() is most commonly used with xsl:result-document to update parts of the document identified by the href attribute. The principal XSLT output (if any) is inserted at the end of the HTML body element.

Note: An error is raised if the source is set to the same document as the target. To read nodes in the HTML you're updating within the XSLT, use the ixsl:page() function which returns the Document node of the host page.