Settings

Visual Studio Code's settings let you tailor your working environment to fit requirements for specific languages or extensions, or to suit your own preferences.

A general guide to settings is provided by the Visual Studio Code documentation: User and Workspace Settings. The page you are reading now covers settings that are of particular interest from an XSLT or XPath development viewpoint.

Creating User and Workspace Settings

From the Command Palette (⇧⌘P) you can either invoke Preferences: Open User Settings or Preferences: Open Workspace Settings. Editor settings can also be applied in a language-specific way, for this, use the command Preferences: Configure Language Specific Settings.

Settings are either edited in the Settings form opened or in a JSON editor. Open the JSON editor by clicking the Open Settings (JSON) button at the top right of the Editor Group (see screenshot). This opens the corresponding settings.json file directly.

XSLT Extension Specific Settings

Type xslt to show a short-list of settings specific to XSLT:

XSLT Packages

To allow XSLT package names to be resolved to file paths, package details should be added to the setting XSLT.resources.xsltPackages.

Sample XSLT package settings

"XSLT.resources.xsltPackages": [
  { "name": "example.com.package1", 
    "version": "2.0", 
    "path": "included1.xsl"
  },
  { "name": "example.com.package2",
    "version": "2.0", 
    "path": "features/included2.xsl"
  },
]

XML Catalog

To resolve the href of xsl:import and xsl:include with an OASIS XML catalog - and pass the catalog to Saxon when a stylesheet is run - set XSLT.resources.catalog to the catalog file's path, relative to the workspace folder. See XML Catalogs.

"XSLT.resources.catalog": "catalog.xml"

XSLT Tasks

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

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

XSLT 4.0 Item Types and Notes in XSLT 3.0

Saxon PE and EE 12.8 or later, run with syntax extensions, accept XSLT 4.0's named item types and xsl:note in a stylesheet with version="3.0". To edit such stylesheets with the same support as for XSLT 4.0, enable the setting XSLT.validation.xslt30ItemTypesAndNotes - it's off by default. For a team, add it to the workspace settings, in the project's .vscode/settings.json:

"XSLT.validation.xslt30ItemTypesAndNotes": true

With the setting, in an XSLT 3.0 stylesheet:

xsl:item-type declarations are accepted, with record(...) and enum(...) types - which can also be used directly in as attributes
the record and enumeration type support applies: completions of record fields, map keys and enumeration values, checks of map constructors, lookups and values, hover help, and renaming a record field
xsl:note needs no use-when attribute - see Documentation Notes

Other XSLT 4.0 and XPath 4.0 features - such as xsl:switch, keyword arguments and fn(...) types - still need version="4.0", and are reported as errors in an XSLT 3.0 stylesheet.

Without the setting, xsl:item-type and record and enumeration types are reported as errors in an XSLT 3.0 stylesheet, and an xsl:note gets a warning unless it's excluded with use-when="false()", as an XSLT 3.0 processor reports XTSE0010 for it.

To run the stylesheets, Saxon needs syntax extensions: the --allowSyntaxExtensions:on option on the command line, or allowSyntaxExtensions="true" in a Saxon configuration file. The extension's XSLT tasks and Quick Run enable it with the default "allowSyntaxExtensions40": "auto" task property, for Saxon PE and EE.

Saxon type aliases: Saxon's earlier syntax for named types - saxon:type-alias, tuple(...) types and ~name for a reference to a type alias - is ignored by Saxon 12.8 and later, which only report the references. The linter warns about a saxon:type-alias, and the command XSLT: Convert Saxon Type Aliases to xsl:item-type - also the warning's quick fix - converts them in all the workspace's files, shown for review in the refactor preview first:

<saxon:type-alias name="dfx:bounds" type="..."/> becomes <xsl:item-type name="dfx:bounds" as="..."/>
tuple(t: xs:integer, label?: xs:string) becomes record(t as xs:integer, label? as xs:string)
as="~dfx:bounds" becomes as="dfx:bounds"

A type alias with an extensible tuple type, e.g. tuple(a: xs:string, *), isn't converted - nor is one that references it - as XSLT 4.0 has no extensible record types. These are listed after the conversion, to convert by hand.

General Settings For XSLT

Configuration Settings From the Extension

This extension includes default configuration settings for XSLT editing features. These features include formatting, word-selection, and syntax-highlighting using semantic-tokens. You can set your own preferences for XSLT and XML editing. The language labels ensure these settings don't affect coding in other languages.

The default configuration user-settings - overridable in settings.json

"...
[xslt]": {
  "editor.defaultFormatter": "deltaxml.xslt-xpath",
  "editor.formatOnSaveMode": "file",
  "editor.formatOnSave": false,
  "editor.formatOnPaste": true,
  "editor.formatOnType": true,
  "editor.semanticHighlighting.enabled": true,
  "editor.detectIndentation": true,
  "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$",
  "editor.insertSpaces": true,
  "editor.tabSize": 2,
  "outline.showArrays": false
},
"[xml]": {
  "editor.defaultFormatter": "deltaxml.xslt-xpath",
  "editor.formatOnSaveMode": "file",
  "editor.formatOnSave": false,
  "editor.formatOnPaste": true,
  "editor.formatOnType": true,
  "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$",
  "editor.detectIndentation": true,
  "editor.insertSpaces": true,
  "editor.tabSize": 4,
  "outline.showArrays": false
}
...

Code Formatting

The following settings directly affect code formatting in the XSLT/XPath extension:

    "editor.defaultFormatter": "deltaxml.xslt-xpath",
    "editor.formatOnSaveMode": "modifications",
    "editor.formatOnSave": true,
    "editor.formatOnPaste": true,
    "editor.formatOnType": true,

The editor.formatOnSaveMode setting can be used to only format XSLT lines changed since the last commit on Git.

Syntax Highlighting

Syntax highlighting for XSLT and XPath is achieved using Visual Studio Code's Semantic Highlighting tokens alone. Almost all other languages in Visual Studio Code use a TextMate Grammar for tokens which may be supplemented by Semantic Highlighting.

If XSLT and XPath is not syntax highlighted in any Color Theme, you can explicitly enable Semantic Highlighting with the setting:


        "editor.semanticHighlighting.enabled": true

The XSLT Dark Themes extension provides a selection of popular dark color themes, enhanced for XSLT/XPath.

Screenshot of Gruvbox Theme extended for XSLT

X Gruvbox Material Dark theme:

Word Separators

The editor.wordSeparators setting affects how the full 'word' is selected when you double-click on a part of the word. The characters listed are used as word separators. Typically in XSLT, you do not want characters like - and . treated as word separators as these characters are valid within a QName like an attribute name or a variable name.

Emmet Snippets

Emmet Snippets provide a convenient shorthand for inserting a number of literal result elements and attributes into your XSLT in one go. For example, entering:

ul>li.item$*2

provides the following output:

      <ul>
          <li class="item1"></li>
          <li class="item2"></li>
      </ul>

To enable Emmet snippets for XSLT, add the following setting:

        "emmet.includeLanguages": {
          "xslt": "xml"
        },

XSLT and XPath

for Visual Studio Code