TextExpander 5 JavaScript snippets

I mentioned the release of TextExpander 5 last week, and the fact that it now allows snippets to be written using JavaScript.

You can find the documentation for JavaScript in TextExpander in the help book. I started playing with it a bit over the weekend, and thought I’d share a couple of findings.

To start a JavaScript snippet, create a new snippet and change the type dropdown at the top of the edit field to “JavaScript.” Standard JavaScript is available, and JavaScript for Automation can be used. The latter will only work on OS X.

Nested snippets work quite well, so you can create snippets containing JavaScript libraries and include them in other snippets. Just give them long names that you’ll never type, and then reference them using the %snippet:longJSLibrarySnippetName% format at the top of your JavaScript snippet. I had the best results when setting the snippet type of included snippets to “Plain Text.”

In the JavaScript context, there’s a TextExpander object with some special values and functions. These are well documented in the help. The TextExpander.appendOutput() function is a way to incrementally build the return results. Just use TextExpander.appendOutput(newOutput) and it’s added to the output results. The final output of the script is what will be inserted when the snippet is triggered.

You can get the abbreviation the script was triggered with using TextExpander.triggeringAbbreviation, and the Bundle ID of the application the snippet was triggered in using TextExpander.expansionContext. These allow you to build logic that provides different responses based on these variables, potentially allowing snippets code to be re-used. For example, you could build one snippet that handled five different abbreviations, then nest it into five snippets. Each snippet would pass its own abbreviation to a case statement in the main script, and perform actions without having to rewrite the script five times.

Filled values are available in the TextExpander.filledValues object, with keys based on the field name. If you have a fill-in named “Format”, you can retrieve its value using TextExpander.filledValues['Format']. You can also use fill-ins directly in JavaScript code, and use the new %filltop% placeholder in the script to have the fill-in popup show only the options without displaying the entire script. That’s a very cool addition that I’ll be incorporating across a lot of the TE-Tools.

As an example of some of my experimentation, I’ve added a new group to the TE-tools called “Next X.” It provides a JavaScript strftime library, which it nests into snippets for each day of the week¹. Then you can use nd.tue to insert the date for the next Tuesday in the calendar while typing. nd.sun through nd.sat are available.

By default, dates are inserted in the format “Tuesday, June 02.” Each snippet has a line at the top like this:

var fmt = '%A, %B %d';

You can use strtime format placeholders to change that to whatever is most appropriate for your locale/preference.

There’s also a snippet called nd.x which offers a fill-in popup where you can select a day of the week and a date format. This one is an example for building your own and customizing.

You can also change the prefix, but the script requires the dot and then the 3-letter abbreviation for the weekday to be at the end of the abbreviation, e.g. myPrefix.mon.

You can grab the snippet group from the TE-snippets page, and get more information about available groups on the TE-Tools project page.