Introduction
Taxi for Email simplifies the task of building a great-looking email. Unlike other block-based editors, you don’t just use the building blocks that the editor provides. Instead, you (or our team) sets up the precise HTML that you want to use via your Email Design System (EDS). This works by extending ordinary HTML language with Taxi Syntax to enable you to control exactly what you want to be editable in the block-based editor, and how it’s editable.
This approach is powerful and gives you huge productivity gains, but needs some up-front effort to create and maintain the EDS file. I asked our own Taxi experts how they create and maintain the EDS text files, and found the team uses a variety of editors – Visual Studio Code and Atom are among their current free open-source favorites.
In this post, we’ll walk through a free open-source Taxi syntax validator extension for VS Code, that uses the Taxi API.
In a hurry? This is all you need
- Download Visual Studio Code if you don’t already have it
- Follow these instructions to obtain your API key.
- In the left menu, choose Extensions (the square boxes icon).
- Search for and install the Taxi for Email Extension. The README help is shown there.
- On the settings gear wheel, configure your Taxi for Email API credentials.
- Open the command palette, search for Taxi, and validate. You can also assign a shortcut key.
The rest of this blog shows the motivation for this work, and how the new Taxi API makes it possible.
Motivation
When edits are made to the EDS file, you need to upload it to your Taxi account. This is straightforward via the web UI, however, it is at this point you see error messages or warnings telling you that your EDS file isn’t quite right. You need to read and understand the error message, then go to the relevant section in your EDS file, make corrections, and try uploading again.
This is the classic “Edit, Compile, Run” debugging cycle familiar to all old-school developers. While it’s possible to become swift at navigating the screens, clicking and dragging the new file over, checking the results, then jumping back to the editor, it saps mental energy and breaks your flow. I’m used to working with debug and linting support built into my code editor, so I wanted something similar for Email Design Systems.
“Linting” is developer jargon for checking if your program adheres to your chosen language’s precise rules. The name derives from picking off the tiny bits of fluff (aka lint) shed by your clothing! In the 1970s, Bell Labs developers working on Unix came up with a tool called “lint”, and the name has stuck ever since.
The API cometh
When I heard we were working on an API for Taxi that would support remote validation of Email Design Systems, this offered huge potential to improve workflow in a couple of aspects.
The API was conceived as a way of running automated checks on your Email Design System as you upload changes into a version control system such as Github, via Continuous Integration (CI), viewing the errors and warnings on the log file output. While this is excellent, there’s an inevitable time lag between checking in a change and being able to see the output. If you’ve just introduced an error, you need to fix, check in a new revision, and so on. My wish was to validate directly from the editor – before you’ve committed changes.
Visual Studio Code extensions
Visual Studio Code has a Marketplace for extensions. In fact, these are almost all free (and open-source), because the editor itself is free and open-source. There are tens of thousands of published extensions. A quick look at the “Build your Own” pages with good quality documentation and examples convinced me to try it. Extensions are written in TypeScript – this would be my first experience of this dialect. VS Code offers classes that help you to extend the editor quite easily.
Extensions work nicely with Github. The README file in the Github repo serves as user documentation for your extension within Visual Studio code. You can use VS Code to debug your extension (with breakpoints, stepping, variables display, etc).
You can distribute your extension privately as a .VSIX file – that’s how I started off my first users for beta testing. You can then register as a publisher on the Marketplace and make it publicly available.
Inside the code
Calling the Taxi API from the extension requires a “requests” type library. I chose Axios, as we use this elsewhere in SparkPost.
The main code file in src/extension.ts is less than 200 lines. It registers a command called taxitest.validateEDS which does the work. The active document text is read directly via a stream buffer, so you don’t even need to save your work before validating it.
Like other language tools, results are presented in the editor “Problems” panel. The extension uses the vscode.Diagnostic class to show results with highlighting, keyed by the line number of the error/warning returned from the API. Clicking on an error/warning automatically highlights it in the editor window. Double-clicking jumps your cursor to the offending line.
Validation can take a few seconds on large files (~ 5 .. 10 seconds for a 4000 line file), and you need an Internet connection. For these reasons, unlike some language plugins, it doesn’t run all the time in the background.
The repo includes automated tests of the code, run via Github Actions, on MacOS, Ubuntu and Windows.
This is a volunteer open-source project and is not directly supported by the Taxi for Email support service. If you find an issue, please open an issue in Github, or (even better) – contribute a pull request.
Possible future improvements
The Taxi API now supports direct upload of email design systems. Is this a worthwhile feature to add?
Do you have another editor (with extensions) you’d like to be able to validate your EDS from? Get in touch via Twitter @SparkPost or Github.
