XSLT Tasks

The XSLT/XPATH extension allows XSLT files located within a VSCode Workspace Folder to be compiled and run using one of the following XSLT processors from Saxonica.

• Saxon (Java-Processor)
• Saxon-JS 2.0 (JavaScript-Processor for Node/Browser)

A custom VSCode XSLT Task Provider allows for the management of a set of tasks used to define XSLT transform configurations. Each configuration is used to control the environment in which an XSLT transform runs.

When a task is run from VSCode, the Saxon XSLT processor is invoked via its command line interface. The VSCode Terminal View will show the stdout from Saxon. The stdout is also processed by the extension to check for compile time or run time errors. Most errors (the generic error parser is not faultless) will also be highlighted in the VSCode Problem View and highlighted in the code editor. The extension also includes its own code diagnostics to provide as-you-type error reporting.

Managing XSLT Tasks in VSCode

XSLT transforms can configured and run with Saxon (Java) or Saxon-JS using VSCode tasks. This feature provides a convenient way to manage one or more XSLT transform configurations in a JSON file for a project. The built-in template for an XSLT task configuration runs the current XSLT file with this same file set to the input of the transform. Auto-completion in the JSON files show the available JSON property settings and a brief descriptions. These settings correspond to Saxon command-line arguments.

See XSLT Tasks for a detailed description.

• Ensure you have a Folder or Workspace Folder open in VSCode

• In VScode, press Shift-CMD-P then enter 'tasks:' to see Task Commands:

Select the 'tasks: Configure Task' command, a list of tasks will be shown:

The existing tasks, plus two 'xslt(xslt-js): Saxon Transform (New) entries are listed, as shown above, select this last entry to create a new task.

If a new task is created the 'label' property should be edited to describe the specific task.

To run a task, press Shift-CMD-B. If there's no default task, select the required task from the list that is shown.

Problems Panel

Any compile-time or run-time errors/warnings are shown in the VSCode Problems panel. Select an item in the Problems panel, to see the problem highlighted in the XSLT.

Defining XSLT Transform Tasks

Each task can be configured to set options and XSLT parameters for an XSLT Transform. VSCode Variables like ${workspaceFolder} can be used within properties in a task configuration.

Sample tasks.json

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "xslt",
			"label": "Basic Transform",
			"saxonJar": "${config:XSLT.tasks.saxonJar}",
			"xsltFile": "${workspaceFolder}/basic.xsl",
			"xmlSource": "${workspaceFolder}/basic.xsl",
			"resultPath": "${workspaceFolder}/xslt-out/result1.xml",
			"parameters": [
				{"name": "p1", "value": "p1value"},
				{"name": "p2", "value": "p2value"}
			],
			"initialMode": "main",
			"classPathEntries": ["/xrc/utilitiy.class1", "/xrc/utility.class2"],
			"group": {
				"kind": "build"
			},
			"problemMatcher": [
				"$saxon-xslt"
			]
		},
		{
			"type": "xslt",
			"label": "Compile Active XSLT File",
			"saxonJar": "${config:XSLT.tasks.saxonJar}",
			"xsltFile": "${file}",
			"xmlSource": "${file}",
			"resultPath": "${workspaceFolder}/xslt-out/result1.xml",
			"group": {
				"kind": "build"
			},
			"problemMatcher": [
				"$saxon-xslt"
			]
		}
	]
}

Saxon Configuration for Java

Saxon can be downloaded from the Saxon Downloads. Saxon 9.9 or later must be installed on the local machine. By default, the location of the Saxon Jar should be set in User Settings for the XPath Embedded extension.

Alternatively, the saxonJar property in tasks.json can be modified to use a value other than that set in User Settings.

Setting the Saxon Jar location in VSCode User Settings:

Saxon-JS Configuration for Node

A XSLT-JS task invokes Saxon-JS using the Node npx command-line. For each task, the npx locates the Saxon-JS xslt3 package used. To install Saxon-JS:

1. Create a new project folder if you don't already have one:

mkdir <myproject>

2. Open the project folder in VSCode and in the terminal view set the project folder to be the current directory:

cd <myproject>

3. Use NPM to install Saxon-JS as a developer dependency:

npm init -y
npm install --save-dev xslt3

---

Disabling Tasks for Saxon XSLT-Java and XSLT-JS

The Saxon XSLT-Java and XSLT-JS TaskProviders are enabled by default. These can be enabled/disabled using the following settings properties:

"XSLT.tasks.java.enabled": true
"XSLT.tasks.js.enabled": true