To get the best results from DeltaXML’s XML Document Comparator, you can tailor its configuration, both for specific input document types and for specific outputs. This article shows how to develop the Document Comparator Pipeline (DCP) configuration file using features from DeltaXML’s free XSLT/XPath extension for the popular Visual Studio Code editor. For the rest of this article, I’ll refer to Visual Studio Code as ‘VS Code’ and assume this extension is installed.
Editing DCP with embedded XPath expressions in VS Code
DeltaXML’s DCP format is defined in an XML Schema (1.0 and 1.1 XSD versions are included).
An XML-Schema 1.1 compatible XML editor like OxygenXML (which many of our customers use) is more than sufficient if you are developing a relatively basic DCP file for DeltaXML’s Document Comparator, perhaps with just one or two ‘pipeline parameters’.
VS Code’s DCP editing features provides the same basic features as other such editors, however, it comes into its own when you need a more adaptable DCP configuration, possibly with embedded XPath expressions and a number of pipeline parameters. This might be the case for example, when you’re using the Document Comparator’s REST API.
In Visual Studio Code, create a new file and save it as ‘test.dcp’. The ‘.dcp’ filename extension is recognised and causes ‘DCP’ to be shown in the ‘Language Mode’ part of the status bar at the bottom of the editor.
At the top of the new file editor, enter ‘<' (as you would normally do when adding a new XML element), you will be presented with a list of available ‘code snippets, select ‘Standard Configuration DCP’ from the list. A basic element-structure for a standard DCP is inserted into the editor, with the ‘id’ attribute of the 'documentComparator’ element pre-selected so you can edit this directly. You now have a valid DCP file that you can save again and then invoke from the command-line using the given 'id’ value.
In the editor, type ‘<' to see a list of available DCP snippets
As you edit the DCP file, you will be presented with auto-completion options according to the element or attribute context. If an element-name, attribute-name or attribute-value is invalid, a warning will be shown.
Note: With other XML editors like OxygenXML you can also get this behaviour, you will just need to copy our DCP schema to your file-system and then either create a ‘validation scenario’ or add the relevant
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" namespace and
xsi:noNamsepaceLocation attribute declarations.
VS Code’s context-aware auto-completion list
The DCP format supports
booleanParameter elements, each with a
name attribute. These elements have
default attributes with values that can be overriden from the GUI or Command-line user-interfaces or from our REST or Java APIs.
Parameter element is declared but the
name is not referenced within the DCP, then the
name attribute is shown grey-out.
Any DCP element that corresponds to a DocumentComparator setting or an XSLT filter parameter can have one of three attributes:
The VS Code editor will mark as invalid any
parameterRef attributes that do not match the
name of the appropriately typed (string or boolean)
Parameter element. Other XML editors can show associated XML Schema 1.1 assertion error messages but they cannot highlight the specific
parameterRef attributes at fault.
DocumentComparator or XSLT filter parameters can be set with an
xpath attribute, other attributes (like
file elements) allow XPath expressions to be enclosed within curly-braces in the same way as XSLT’s attribute-value-templates (AVTs).
For XPath expressions within the DCP, the VS Code editor provides special syntax-highlighting, basic XPath syntax-checking, variable-reference checking and auto-completion.
To help navigate larger DCP files, the Outline View in the Explorer pane shows a tree-view of the DCP file, with special highlighting for parameters etc. Several other VS Code navigation features have been extended with specific support for DCP.
XSLT filters can be inserted into specific parts of the Document Comparator pipeline with the DCP format. XSLT filters for user-defined files or built-in resources are declared as
resource elements within an element representing a specific ‘extension-point’ in the pipeline.
To add a new XSLT file to the pipeline, enter the relative path for the XSLT in the
path attribute that is added with auto-completion. If the XSLT file does not exist, a squiggly-line appears under the path, hover over this to show an ‘action popup’ and then click ‘Follow Link’ on the popup and then click on the ‘Create File’ button.
Click on the ‘Follow Link’ popup-action to create a new XSLT file
You can choose to edit the XSLT filter within VS Code with full XSLT language support from DeltaXML’s extension (see our XSLT/XPath User Guide) or use your own preferred XSLT editor. In VS Code, an XSLT snippet creates a boiler-plate ‘identity transform’ XSLT filter that can be quickly modified to suit your requirement.
The Document Comparator is distributed with a set of built-in XSLT resources. When inserting a built-in XSLT resource, auto-completion is provided for the
name attribute of the
resource element. The auto-completion list is populated with the names of all built-in XSLT resources.
Choosing an XSLT filter resource-name from the auto-completion list
This article has outlined how DeltaXML’s VSCode extension supports XSLT and DCP language features, providing a dedicated environment to help manage the configuration of a Document Comparator Pipeline. If you want to try it out please install the extension from the VS Code MarketPlace or directly from VS Code.