Working With AppleScript and Shell Script Snippets

AppleScript Snippets

In the content format drop-down menu, choose “AppleScript” as the format type. In the content field, enter an AppleScript such as this one:

(Adjust values in quotes in the list below to your preferred greeting for the following script):
return some item of {“Sincerely”, “Yours Truly”, “Peace Out”, “Have a good day”, “kthxbai”}

The script executes in the context of the TextExpander application. The script can perform various actions such as controlling or requesting information from other applications, but the snippet
will expand to whatever text is returned. The script should not use display dialog or display alert because all keystrokes are buffered while the snippet is expanding.

You can use AppleScript to change many of TextExpander’s preferences or to add or remove snippets and groups.

AppleScript is not compatible with Windows or Chrome OS. Expanding an AppleScript Snippet in these OS’s will result in a message of “AppleScript expansion not supported.”

Scriptable Preference Settings

The preferences you can access or change via AppleScript include some of the settings available in TextExpander’s Preferences window as well
as several settings which do not have any corresponding controls.

expansion enabled
A boolean flag controlling whether expansion (and capitalization correction) is enabled.
(See Expansion Preferences)
include HTML
A deprecated flag.
restore pasteboard

A boolean flag controlling whether the previous pasteboard contents are restored after Pasting snippet content.
(See Expansion Preferences)

Note: If this flag is set, and your clipboard history utility is showing TextExpander expansions in the history, direct the developer to www.nspasteboard.org.

capitalize new sentences
A boolean flag controlling whether capitalization correction automatically capitalizes the first word new sentences.
(See Options Preferences)
suppress double capitals
An enumeration controlling whether capitalization correction corrects two capital letters at the start of a word to just one.
(See Options Preferences)
restore clipboard regardless

A boolean flag controlling whether TextExpander will restore a clipboard that does not match the snippet content that it placed there to expand a snippet. This is useful if an application or utility modifies the contents of the pasteboard.

For example, TextMate 1.5.10 modifies the pasteboard as soon as text is placed on it, resulting in TextExpander not restoring the previous clipboard contents.

avoid Caching Embedded Snippets
A deprecated flag.
notify on Secure Input

A boolean flag controlling whether TextExpander will present a notification when Secure Event Input is engaged outside of a secure text field.

The default value is true.

generate suggested snippets

A boolean flag controlling whether TextExpander will suggest snippets based on analyzing typed text. Corresponds to the “Suggest snippets based on my typing habits” preference.

The default value is true.

notify when suggesting

A boolean flag controlling whether TextExpander will present a notification when suggested snippets are created.

The default value is true.

avoid suggesting in bundles
A list of text strings with the bundle IDs (ex. com.apple.Terminal) of applications where typing should be excluded from suggested snippet analysis.
preview executes scripts
A deprecated flag.
tutor Typed Snippets

A boolean flag controlling whether TextExpander will present a notification when you type the contents of a snippet when you could have used the abbreviation instead. Corresponds to the “Notify me of the abbreviation when I type a snippet that already exists” preference.

The default value is true.

tap key up events

A boolean flag controlling whether TextExpander will tap key-up events as well as the key-down events that it normally taps to detect when you type a snippet abbreviation.

This can help make TextExpander work better with other applications or hardware drivers that generate artificial keystrokes, such as Nuance’s Dragon products, or the Microsoft IntelliPoint mouse driver.

avoid querying keyboard layout

A boolean flag controlling whether TextExpander will avoid querying the active Input Methods for keyboard layout information.

This can help avoid slow typing with certain Input Methods, such as the Sugou IM. However, it also prevents TextExpander from detecting the correct ‘V’ key
(for sending Command+V to Paste in snippet expansions) when using, for example, the Dvorak keyboard layout.

always pause before Pasting

A boolean flag controlling whether TextExpander will pause briefly before Pasting, regardless of which application is active while expanding a snippet.

TextExpander places the snippet expansion on the clipboard, then immediately sends Command+V to Paste it in. Some applications seem
to require a short delay in order for the new clipboard contents to “register” and the expansion to work as desired. A pause before Pasting can
help overcome problems with the pasteboard contents appearing instead of a snippet expansion, possibly because some clipboard utility is modifying or
otherwise slowing the change of the pasteboard.

By default, TextExpander pauses before Pasting in: Pages, Numbers, Keynote, Mail, Spotlight, Fantastical, Xcode, and most Microsoft applications.

pause before Pasting bundles
A list of text strings with the bundle IDs (ex. com.apple.Safari) of additional applications to pause before Pasting into (the default applications are listed above).
pause before Pasting time
A real number controlling the number of seconds TextExpander will pause before Pasting (when pause applies). The default value is 0.2 seconds.
pause after Pasting bundles

A list of text strings with the bundle IDs (eg. com.apple.Safari) of additional applications to
pause after Pasting into.

After TextExpander sends Command+V to Paste in snippet content, it may send additional keystrokes very quickly immediately afterwards.
If you are expanding with delimiters, or your snippet contains Tab, Return, etc. keystrokes, or arrow keys are required to place the
insertion cursor at some location within the snippet, some applications seem to require a short delay to process the Paste before
receiving subsequent keystrokes. If snippet parts are appearing in the wrong order or wrong locations, try adding the application to this list.

By default, TextExpander pauses after Pasting into: Pages, Numbers, Keynote, Microsoft Word, Microsoft Powerpoint, Safari, Google Chrome, Firefox, Camino, and SeaMonkey.

pause after Pasting time
A real number controlling the number of seconds TextExpander will pause after Pasting (when pause applies). The default value is 0.2 seconds.
pasteboard data types to avoid accessing

A list of text strings of pasteboard data types that TextExpander should avoid accessing when saving and restoring the pasteboard.

Some pasteboard data types represent data that is “promised” to the pasteboard, but not actually present on the pasteboard. When TextExpander tries to copy the pasteboard before inserting a snippet, some of these “promised” data types take a long time to actually be provided, sometimes slowing expansion or causing instability.

If restore pasteboard is enabled, data types in this list will not be restored to the pasteboard after TextExpander expands a snippet.

avoid expansion bundle prefixes

A list of text strings with the bundle IDs (or partial prefixes, eg. com.mozilla will cover com.mozilla.firefox
and com.mozilla.camino, etc.) of applications to avoid expanding or correcting capitalization in.

By default, TextExpander avoids expanding into applications where the bundle ID begins with com.parallels or com.vmware.

This can be useful to prevent TextExpander from interacting with certain applications or Java applets which do not appear in the “all applications, except…” listing in Expansion Preferences.
(To prevent expansion in Java applets, add com.apple.javajdk16.cmd to this list (change appropriately for different versions of the JDK).)

allowed computation time
Seconds before snippet content computation times out. By default, TextExpander allows script snippets 5 seconds to compute. This value can be adjusted up to 28 seconds if some of your script snippets take a long time to execute.
unibar bundle_role_identifier triplets

A list of strings in triplets:

  • Bundle ID – application bundle identifier such as com.google.Chrome (used in a case-insensitive comparison)
  • AXRole – the Accessibility Role of a focused text item, such as AXTextField, or an empty string for both this and AXIdentifier to match any typing in the given Bundle ID
  • AXIdentifier – the Accessibility Identifier of a focused text item, such as WEB_BROWSER_ADDRESS_AND_SEARCH_FIELD (note, if an empty string is provided, all areas with the given AXRole will be matched)

These triplets define text areas within applications where Shift-Left-Arrow keystrokes will be used to remove/replace the snippet abbreviation instead of the usual Backspace. (Browser “unibars” and other auto-completed text areas respond better to Shift-Left-Arrow keystrokes.)

ignore clicks in bundles

A list of text strings with the bundle IDs of applications to allow mouse clicks in without resetting the typing log (eg. virtual keyboards).
That is, usually any mouse click will clear the typing log, so if you type part of an abbreviation, click the mouse, then finish the abbreviation, TextExpander will not expand the snippet.

By default, TextExpander ignores clicks in: the system’s KeyboardViewer, KeyStrokes (by AssistiveWare), and VirtualKeyboard (by Corallo Software).

expand using RTF bundles

A list of text strings with the bundle IDs of applications to expand formatted text snippets using RTF in. TextExpander usually uses HTML for formatted text expansion.

By default, TextExpander uses RTF for formatted text in: Microsoft Word, Pages, TextEdit, and Bean. This setting adds additional bundle IDs.

sample font for RTF

A boolean flag controlling whether TextExpander will attempt to Cut (via Command + X) part
of the abbreviation to determine the current font and size applied to the text it is expanding in for
applications where RTF is used for formatted text expansions.

By default, TextExpander will attempt to “sample” the font to produce better results in
applications that prefer RTF.

avoid sampling bundles

A list of text strings with the bundle IDs of applications where TextExpander should not attempt
to Cut (via Command + X) part of the abbreviation to determine the current font and size.
Only applies to applications where RTF will be used for expansion, and can be overridden by turning
sample font for RTF off.

use points for font size

A list of text strings with the bundle IDs of applications where TextExpander should specify font sizes
in points, instead of the usual pixels, when expanding formatted text.

By default, TextExpander expands this way in Microsoft Outlook and OneNote.

fonts in points URLs

A list of records with bundle IDs of web browsers, URL-fetching AppleScripts, and URL prefixes where TextExpander should specify font sizes
in points, instead of the usual pixels, when expanding formatted text.

By default, TextExpander expands this way in Safari and Google Chrome when the URL indicates expansion into
a Google Docs page.

expand with repeated keys
A boolean flag controlling whether TextExpander will expand snippets when keys are held down to repeat letters. By default, repeated keys do not trigger expansion or capitalization correction.
wait for modifier release
A boolean flag controlling whether TextExpander will wait for shift/option/control/command modifier keys to be released before expanding snippets. By default, TextExpander waits for these keys to be released before expanding in case they affect how snippet content is Pasted in.
non expanding language codes

A list of text strings with the two-letter language codes of Input Methods where expansion is disabled.

By default, TextExpander does not expand when using Input Methods identified with any of the following language codes: “ja”, “zh”, “sa”, “ar”, “hi” (Japanese, Chinese, Sanskrit, Arabic, Hindi).

additional contraction characters
A text string containing punctuation characters in addition to apostrophe and right single quotation mark to be treated as letters by capitalization correction. (eg. “i’m” corrects to “I’m”)
adjust linebreaks after empty optional parts
A boolean flag controlling whether TextExpander will try to remove what will seem like an extra blank line if an optional section
of a fill-in snippet is not included. That is, if an optional section which starts on a new line is not checked, and there is a line break just afterwards, that linebreak will not be expanded in the snippet. TextExpander defaults to performing this adjustment.
adjust linebreaks after linebreak keystrokes
A boolean flag controlling whether TextExpander will avoid expanding what may be an extra blank line if a
%key:return% or %enter% is followed by a line break. TextExpander defaults to performing this adjustment.
allow zero width space

A boolean flag controlling whether TextExpander will allow zero width space characters to be expanded as part
of snippet content. Through Pasting and various means, zero width space characters sometimes end up in snippet content
but can cause problems, so TextExpander defaults to stripping them out.

event generation timeout
The fraction of a second that TextExpander will wait for a posted event to appear before assuming it will not appear. If events appear slowly on your system, increasing this slightly can improve expansion results. TextExpander defaults to 0.175 second.
include paragraphs in HTML
A deprecated flag.

Scripting Snippets and Groups

You can use AppleScript to access Snippet Groups by name, or you can enumerate through all the groups. Once you access a group, you can enumerate the snippets it contains. Group and snippet properties can be edited. You can create or delete groups or snippets.

Please note: This functionality is no longer available in TextExpander 6.8+.

Here is a sample script that changes any Formatted text snippets in the My Snippets group to be Plain Text snippets instead:

tell application “TextExpander”
set theGroup to group “My Snippets”
set theSnippets to snippets of theGroup
repeat with theSnip in theSnippets
if ((content type of theSnip) = rich_text) or ((content type of theSnip) = formatted_JSON) then
set the content type of theSnip to plain_JSON
end if
end repeat
end tell

Expanding Snippets

You can use TextExpander’s expand command to expand a snippet into the currently active application. You can either
specify a snippet reference (expand snippet aSnippet),
or you can provide a snippet abbreviation (expand abbreviation “abbreviation”).

Please note: This functionality is no longer available in TextExpander 6.8+.

Here is a sample script that creates a reply to the currently selected message in Mail and inserts a snippet as the reply text:

— create a reply to the currently selected Mail message with a snippet
tell application “Mail”
activate
set current_messages to selected messages of message viewer 1
set theMessage to last item of current_messages
set new_message to reply theMessage with opening window and reply to all

tell application “TextExpander”
expand abbreviation “;fbreply”
end tell
end tell

Shell Script Snippets

In the content format drop-down menu, choose “Shell Script” as the format type. In the content field, enter a shell script such as this one:

#!/usr/bin/perl
print "Hello from Perl!\n";

Your shell script must have the “shebang” (#!) on its first line and that must specify the interpreter to be used for your script.

Here is an example of a Unix shell script:

#!/bin/bash
echo "Hello from Bash!"

The snippet will expand to the standard output of the shell script.

Shell scripts inherit TextExpander’s environment, so no shell configuration or profile, such as .bashrc / .bash_profile, is executed. TextExpander sets LANG to [current locale].UTF-8 before executing a shell script. The result of a shell script must be encoded in UTF-8.