A CALS Table Viewer for Visual Studio Code
June 23, 2022
What are CALS Tables?
The CALS table model is a standard way of representing tabular information in XML. Originally developed for SGML, the XML standard is now published by OASIS [ OASIS - Specs/Documents - Table Models ]. The purpose of the CALS table model is to facilitate table interchange between different tools with a standard way of representing and rendering tables in XML. The CALS table model is included in many other XML standards such as DocBook, DITA, S1000D and JATS.
Background: CALS Table Research Project
When working with our research team at DeltaXML a while back, I was routinely working with sets of XML files containing CALS tables. These files comprised: inputs for tests, the expected results for tests and the actual results from tests.
Our research team quickly accumulated test resources comprising a few hundred files. Input files typically contain a single CALS table. The result file is a ‘diff’ of two (or more) input files, holding the CALS table plus annotations describing differences between the inputs.
To work effectively with these files, we needed to render the XML as regular tables with colour highlighting describing the differences. For this, we developed XSLT to render CALS tables in the XML as HTML that could be opened in any browser.
Requirement: An XSLT-Driven File Viewer
From the CALS Table project, we now had XSLT that could render CALS tables in our XML files as HTML, but how could we flexibly render our XML files just at the moment we needed to? Moreover, we often needed to view several XML files at the same time, this could be a whole directory of files, or just a handful of related files. Related files might, for example, be different comparison results using the same inputs but achieved with different comparator settings.
So, our team needed a file explorer with a CALS table preview, but with extra features so we could efficiently preview more than one file at a time. There was also an aspiration that such a tool could also be useful for our customers. Perhaps to help assess how effective our new CALS table comparison feature fairs was when working with their customer-specific input files.
A ‘Free-Sprint’ Proposal
At DeltaXML, developers follow the Scrum Agile methodology, working in two-week sprints. Every six sprints we have a five-day ‘free sprint’, where we present the work we have done on the fifth day. My proposal for the free-sprint was to develop a solution for our CALS table research ‘file explorer problem’.
I decided to develop this solution as a Visual Studio Code extension that could be completed within the allowed four days. I chose Visual Studio Code as this is a popular free editor and I’m familiar with the extension API and publishing mechanism.
Free-sprints give us the opportunity to explore new technologies or explore new ways of combining existing technologies. The knowledge gained in a free-sprint helps drive future research and development. In this case the idea was to assess how Saxonica’s SaxonJS XSLT processor and Visual Studio Code could work together seamlessly to solve general XML visualisation problems.
Implementation: An XSLT-Driven Renderer for VS Code WebView
I’ve outlined here how this project was implemented, more detail can be found in the source code on the project’s Github Repository:
The VS Code WebView
Visual Studio Code provides a ‘WebView’ feature, accessed via its extension API. The WebView is effectively a Chrome browser environment with features to interface the WebView with the VS Code ‘host’ in a secure way.
main.js script listens for ‘update’ JSON messages from VS Code and converts them into
transform calls on the SaxonJS API. The XSLT is compiled as part of the extension build using SaxonJS’s NodeJS command-line interface.
TypeScript code running within the VS Code extension host is responsible for initialising the WebView and sending/receiving messages to and from the WebView.
Using SaxonJS Interactive extensions for XSLT
SaxonJS provides extensions to XSLT that give extra integration with the host browser environment. The XSLT used in this project exploits these extensions in two ways:
xsl:result-documentinstruction can use a special
hrefattribute value to identify just a specific element in the HTML that is updated. The
methodattribute controls whether content is replaced or appended to.
scrollIntoViewfunction is invoked from within the XSLT so the WebView scrolls to the right position to show appended content.
Using the VS Code Extension
This project has now been published, complete with some extra ‘polishing’ added to the original free-sprint work. The extension is available for installation from the Visual Studio Code MarketPlace here. This adds to DeltaXML’s other VS Code extensions.
The CALS Table Viewer extension is simple to use: Once the extension has been installed, the following commands are available in the Command Palette (⇧⌘P):
- CALS Viewer: File (replace) - view always shows a rendering for the currently selected
- CALS Viewer: File (append) - rendering of each selected file is appended to the view
- CALS Viewer: Directory - all files in the same directory as the selected are rendered in the view
When multiple files are shown in the view, a filename header is shown for each file in the view. If files are not well-formed XML, a message to that effect is shown.
UsingCALS Tables with DeltaV2 markup samples
To help try out this extension, some samples files are included in the cals-tables-samples directory of the project repository.
The main goal of this modest, limited-scope project is now complete. The CALS Table Viewer is now ready to help (while our CALS Table comparator is developed further) maintain our growing test suite comprising XML files with embedded CALS Tables.
This project however, had a secondary goal: to provide a foundation for a more general purpose XSLT-driven file explorer in Visual Studio Code. Hopefully, this goal has also been met, but proof for this awaits further related applications being developed on this platform in the future.
DeltaXML invite you to try out this tool and contact us if you have any questions or suggestions.