Working with JavaScript Snippets

How to create JavaScript Snippets

In the content format drop-down menu, choose “JavaScript” as the format type. In the content field, enter a JavaScript such as an example below.

In the content field, you may enter:

  • Plain old JavaScript, as you might write for a web browser, in an environment provided by TextExpander. This script can also operate in TextExpander for Windows, TextExpander for iPhone and iPad for iOS.
  • JavaScript for Automation (JSA) which is a superset of JavaScript and can be used to automate OS X applications, but it cannot share context with other embedded script snippets, and the expansion text is always the value of the last statement executed in the script. It cannot operate in TextExpander for Windows and TextExpander for iPhone and iPad for iOS.

TextExpander will automatically detect JSA because almost all JSA scripts must contain some specific keywords. If needed, force the script to execute in JavaScript for Automation by setting the first line to: //JSA or // JSA, (a comment with or without a Space to start).

Here is an example of plain old JavaScript:

 a = "Hello, ";
 b = "world!";
 a + b;
 

Here is an example of JavaScript for Automation:

 Mail = Application('Mail');
 firstMessage = Mail.inbox.messages[0];
 firstMessage.subject();
 

In both cases, the snippet expands to the content of the last expression.

The TextExpander environment includes a global TextExpander variable with the following properties:

appendOutput()
This function allows the script to build up the text to be expanded, otherwise the expansion will default to the value of the last statement executed in the script (see also TextExpander.ignoreOutput)
ignoreOutput
A boolean flag the script can set indicating it will return no text for expansion. Useful in the case where the script only has some side effect. Default value is false.
triggeringAbbreviation
The abbreviation of the snippet which triggered the expansion. This will always be its abbreviation as shown in the editor, not the typed abbreviation.
baseDate
A Date holding the time the snippet is being expanded.
adjustedDate
Initially holds the same Date as TextExpander.baseDate, but may hold a different time if a snippet embedding this one used a Date Math macro. The script can modify TextExpander.adjustedDate, then that date will be used for subsequent date and time macros.
pasteboardText
A string with the text contents of the pasteboard. The script can modify this to place the specified text on the pasteboard after the expansion is completed. On Windows this manipulates the clipboard instead.
expansionContext
Will be "com.textexpander.preview" when previewing the snippets, or when creating text to be Copied or Shared. Otherwise:
macOS/iOS — A string with the bundle identifier of the application where the snippet is being expanded. May not always be available.
Windows — A string with the fully qualified path to the application where the snippet is being expanded. May not always be avaiable.
filledValues
Holds fill-in field values as properties, or undefined when snippet is not a fill-in. Text fields, text areas, and popup menus have string values, conditional parts have values true or false. Values are accessed via their field name. If no field name has been specified, a default name is built with the format string "Variable %d". The default name may differ between platforms, so it is recommended to always name your fields.
platform
A string identifying the platform the script is running on, one of: "iOS", "macOS" and "Windows".

If JavaScript snippets are embedded as discussed below, all the scripts share the same context, so global variables created in one snippet are available in the following snippets.

An example TextExpander environment JavaScript snippet, which only adjusts the date used for date macros to four non-weekend days from the current date:

// Find the first non-weekend day four days from now
var p4bd = new Date();
p4bd.setDate(TextExpander.baseDate.getDate() + 4); // add 4 days to current
// skip Saturdays and Sundays
while (p4bd.getDay() == 6 || p4bd.getDay() == 0) {
    p4bd.setDate(p4bd.getDate() + 1);
}
TextExpander.adjustedDate = p4bd; // adjust for all snippets in this expansion
TextExpander.ignoreOutput = true;